From 1d84a2c07ccef6cb570e21722af23d8bf6779538 Mon Sep 17 00:00:00 2001 From: tadamcz Date: Fri, 28 Aug 2026 22:49:39 +0100 Subject: [PATCH 1/7] Rework agent workspace: declared compute layer, drop PyPantograph Replace the accreted apt-Sage/PyPantograph agent stack with a declared compute layer: one locked conda-forge env at /opt/env (compute-env.yaml, exact pins, verified for linux-64 and linux-aarch64), a solvers_build stage for tools with no packaging (kissat, plantri, prover9/mace4, msolve with static FLINT, official cvc5 static binary), a bookworm apt line for the rest, and a loogle_build stage compiling the Loogle Mathlib-search CLI at the FC pin's Mathlib rev. PyPantograph and its two vendored doc trees are removed; the Lean loop is lake env lean + trace_state. The prompt's environment section now advertises the full roster, and tests/test_agent_image.py contract-tests it (new agent-image CI suite). --- .github/workflows/checks.yml | 5 + apn/__init__.py | 2 +- apn/lean/Dockerfile | 278 ++++++++++--- apn/lean/compute-env.yaml | 52 +++ apn/lean/pantograph-docs/LICENSE | 190 --------- apn/lean/pantograph-docs/contributing.md | 42 -- apn/lean/pantograph-docs/rationale.md | 60 --- apn/lean/pantograph-docs/repl.md | 192 --------- apn/lean/pypantograph-docs/LICENSE | 190 --------- apn/lean/pypantograph-docs/agent-search.md | 81 ---- apn/lean/pypantograph-docs/examples/README.md | 24 -- apn/lean/pypantograph-docs/examples/aesop.py | 14 - .../examples/branch-sorry.py | 13 - apn/lean/pypantograph-docs/examples/simple.py | 7 - apn/lean/pypantograph-docs/examples/sketch.py | 41 -- apn/lean/pypantograph-docs/frontend.md | 234 ----------- apn/lean/pypantograph-docs/goal.md | 370 ------------------ apn/lean/pypantograph-docs/intro.md | 79 ---- apn/lean/pypantograph-docs/setup.md | 85 ---- apn/prompts.py | 12 +- apn/redteam.py | 7 +- pyproject.toml | 4 +- tests/test_agent_image.py | 268 +++++++++++++ tests/test_tools.py | 15 +- uv.lock | 2 +- 25 files changed, 576 insertions(+), 1691 deletions(-) create mode 100644 apn/lean/compute-env.yaml delete mode 100644 apn/lean/pantograph-docs/LICENSE delete mode 100644 apn/lean/pantograph-docs/contributing.md delete mode 100644 apn/lean/pantograph-docs/rationale.md delete mode 100644 apn/lean/pantograph-docs/repl.md delete mode 100644 apn/lean/pypantograph-docs/LICENSE delete mode 100644 apn/lean/pypantograph-docs/agent-search.md delete mode 100644 apn/lean/pypantograph-docs/examples/README.md delete mode 100644 apn/lean/pypantograph-docs/examples/aesop.py delete mode 100644 apn/lean/pypantograph-docs/examples/branch-sorry.py delete mode 100644 apn/lean/pypantograph-docs/examples/simple.py delete mode 100644 apn/lean/pypantograph-docs/examples/sketch.py delete mode 100644 apn/lean/pypantograph-docs/frontend.md delete mode 100644 apn/lean/pypantograph-docs/goal.md delete mode 100644 apn/lean/pypantograph-docs/intro.md delete mode 100644 apn/lean/pypantograph-docs/setup.md create mode 100644 tests/test_agent_image.py diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index b8ad96d0..d9eb47a7 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -66,6 +66,7 @@ jobs: --ignore=tests/test_lean_vuln_e2e.py --ignore=tests/test_comparator_security.py --ignore=tests/test_comparator_primitives.py + --ignore=tests/test_agent_image.py - suite: comparator-tests args: >- tests/test_singlefile_proof.py @@ -80,6 +81,10 @@ jobs: tests/test_fc100_isolation.py - suite: gold-proofs args: tests/test_gold_proofs.py + # Contract test for the agent image's declared compute stack (builds + # the agent image in-test, like the other container suites). + - suite: agent-image + args: tests/test_agent_image.py steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v5 diff --git a/apn/__init__.py b/apn/__init__.py index dd2e1e7d..11fd3150 100644 --- a/apn/__init__.py +++ b/apn/__init__.py @@ -1,4 +1,4 @@ __all__ = ["__version__"] -__version__ = "0.1.9" +__version__ = "0.1.10rc1" diff --git a/apn/lean/Dockerfile b/apn/lean/Dockerfile index e1361620..93f87077 100644 --- a/apn/lean/Dockerfile +++ b/apn/lean/Dockerfile @@ -9,9 +9,15 @@ # rename -- the builder detects which from the checkout) # compiles. Shared by the two service images; not a service # itself. -# - agent -- the agent's workspace: base + PyPantograph + numerical -# Python libs. Deliberately contains NO verifier tooling (no -# comparator, no lean4export, no landrun). +# - agent -- the agent's workspace: base + a declared compute stack. +# One locked conda-forge env at /opt/env (python + Sage + +# the python stack + solver binaries; spec in +# compute-env.yaml, built in `compute_build`), apt tools +# conda-forge lacks, source-built solvers (`solvers_build`), +# the Loogle Mathlib-search CLI (`loogle_build`), and +# vendored per-tool docs at /opt/docs. Deliberately contains +# NO verifier tooling (no comparator, no lean4export, no +# landrun). # - comparator -- the trusted verifier: base + the Comparator binary + the # lean4export binary + landrun + the pristine workspace tree. # Replaces the former `compile` + `scorer` pair: the @@ -25,8 +31,9 @@ # # - The FC project (statements, Mathlib, oleans) is pinned by the dataset's # FC_COMMIT and builds with its own lean-toolchain (v4.27.0 today). This is -# dataset identity; PyPantograph's repl must match it (oleans load only -# under the toolchain that built them). +# dataset identity; anything that importModules-loads oleans (lean4export, +# Loogle) must be built at this toolchain (oleans load only under the +# toolchain that built them). # - The lean4export *binary* (the runtime exporter) `importModules`-loads the # project's oleans in-process, so it MUST be built at the project # toolchain. Upstream's rev at that toolchain emits an export format the @@ -42,11 +49,20 @@ # comparator tip only, so its pin tracks the newest tag, not the project # toolchain (plan §2.1). # -# On an FC-pin bump: PyPantograph and the exporter's toolchain move with it. +# On an FC-pin bump: the exporter's and Loogle's builds move with it (Loogle +# is rebuilt against the new pin's Mathlib rev; see `loogle_build`). # On a comparator bump: move LEAN4EXPORT_COMMIT to the rev in comparator's # lake-manifest.json, re-verify the toolchain-override build, and re-run the # primitive-constants check (plan §2.3; the gold-proof suite exercises it). # +# The agent's compute stack is DECLARED, not accreted: the conda-forge env +# spec (compute-env.yaml) plus the explicit install lines in `compute_build`, +# `solvers_build`, and the `agent` stage are the source of truth for what the +# agent can run; tests/test_agent_image.py contract-tests the roster and +# apn/prompts.py advertises it. Loogle is the one deliberately pin-tied +# addition outside the base layer; everything else in the compute stack is +# Lean-agnostic. +# # The builder stage clones the whole formal-conjectures repo and builds the # library; base copies in ONLY the toolchain, the lake build artifacts # (oleans), and the proving-library source. The conjecture corpus (other OEIS @@ -180,18 +196,19 @@ ENV DEBIAN_FRONTEND=noninteractive \ APN_LEAN_PROJECT=/workspace/leanproject # Runtime libs for the Lean toolchain, plus the build tools the derived images -# need (the agent builds PyPantograph; the comparator image builds lean4export) -# and python3 (the agent uses it to drive PyPantograph and as a numerical -# scratchpad). +# need (the loogle_build and lean4export_build stages compile Lean projects) +# and python3 (loogle_build reads the baked manifest with it; the `generate` +# stage drives repo scripts with it). The agent's own python is NOT this one: +# the agent image puts its /opt/env python first on PATH. RUN apt-get update && apt-get install -y --no-install-recommends \ curl git ca-certificates build-essential libgmp-dev \ python3 python3-pip \ && rm -rf /var/lib/apt/lists/* # The Lean/lake toolchain (binaries + the project toolchain). The image ENV PATH -# above covers non-login execs (how ``sandbox().exec`` and the agent's PyPantograph -# subprocess run); add a profile snippet so *login* shells (e.g. ``bash -lc``) -# also find lake/lean. +# above covers non-login execs (plain ``sandbox().exec`` calls); add a profile +# snippet so *login* shells (``bash --login -c``, how the agent's bash tool +# execs) also find lake/lean. COPY --from=builder /root/.elan /root/.elan RUN echo 'export PATH=/root/.elan/bin:$PATH' > /etc/profile.d/elan.sh @@ -218,54 +235,209 @@ COPY --from=builder /staged ./ CMD ["sleep", "infinity"] # --------------------------------------------------------------------------- # -# agent: the agent's workspace. # +# compute_build: the agent's conda-forge compute env at /opt/env (python + # +# Sage + the python stack + solver binaries; spec: compute-env.yaml). Built # +# in its own stage so the multi-GB env is one cached layer COPY'd into agent, # +# re-run only when the spec or the pip pins change. The pip layer installs # +# into the SAME env (no second python): PyPI-only packages, pinned here. # # --------------------------------------------------------------------------- # -FROM base AS agent +FROM debian:bookworm-slim AS compute_build + +ENV DEBIAN_FRONTEND=noninteractive -# PyPantograph commit b8608f3 pins Pantograph v0.3.13, whose repl targets Lean -# v4.27.0 -- matching this track's Mathlib + FormalConjectures oleans. (The repl -# must be built with the same toolchain that produced the oleans it loads.) -# The clone is removed after install so the only importable `pantograph` is the -# installed package (a lingering source tree would shadow it for any python -# started inside /opt/PyPantograph, and the source tree lacks the built repl). -ARG PYPANTOGRAPH_COMMIT=b8608f3 -RUN git clone https://github.com/lenianiva/PyPantograph.git /opt/PyPantograph \ - && cd /opt/PyPantograph \ - && git checkout "${PYPANTOGRAPH_COMMIT}" \ - && git submodule update --init --recursive \ - && pip3 install --break-system-packages --no-cache-dir . \ - && cd / && rm -rf /opt/PyPantograph - -# In-sandbox references for the agent (the sandbox has no network), vendored -# version-matched to the installed package: PyPantograph docs + examples at the -# pinned commit, and Pantograph's repl protocol reference at the submodule -# commit that pin builds. -COPY pypantograph-docs /opt/pypantograph-docs -COPY pantograph-docs /opt/pantograph-docs - -# Numerical/symbolic scratchpad for the agent (the `bash` tool runs python3 in -# this image). The sandbox has no network, so everything is baked in here. -# - sagemath: a full computer algebra system on the `sage` command, bundling -# PARI/GP, FLINT, Maxima, GAP and Singular -- far stronger than sympy for -# number theory (factoring, modular arithmetic, elliptic curves, continued -# fractions) and the dialect much of OEIS's own reference code is written in. -# - python3-{numpy,sympy,mpmath}: importable directly from `python3` (sympy = -# exact symbolic, mpmath = arbitrary precision with pslq/identify). Pulled -# from apt alongside sagemath so all versions resolve mutually consistent -# (a pip --break-system-packages upgrade could outrun what Sage expects). -# This ~1.5 GB install is its own cached layer. +# build-essential + pkg-config: ore_algebra below compiles Cython extensions +# against the env's sage/flint headers (its setup probes flint via pkg-config). RUN apt-get update && apt-get install -y --no-install-recommends \ - sagemath python3-numpy python3-sympy python3-mpmath \ + curl ca-certificates bzip2 git build-essential pkg-config \ && rm -rf /var/lib/apt/lists/* -# CLI tools for the agent's `bash` tool (git is already in `base`): jq for JSON, -# ripgrep for fast search (`rg`). In `agent` so both run conditions get them and -# the agent can be prompted to use `rg` consistently whether or not /corpus is -# present. A cheap layer kept after the sagemath layer so editing it never busts -# that cache. -RUN apt-get update && apt-get install -y --no-install-recommends jq ripgrep \ +ARG MICROMAMBA_VERSION=2.9.0 +RUN arch="$(uname -m)" \ + && case "$arch" in x86_64) plat=linux-64 ;; aarch64) plat=linux-aarch64 ;; *) echo "unsupported arch $arch" >&2; exit 1 ;; esac \ + && curl -sSfL "https://micro.mamba.pm/api/micromamba/${plat}/${MICROMAMBA_VERSION}" \ + | tar -xj -C /usr/local bin/micromamba + +COPY compute-env.yaml /tmp/compute-env.yaml +RUN micromamba create -y -p /opt/env -f /tmp/compute-env.yaml \ + && micromamba clean -afy + +# PyPI-only packages, into the same env. snappy is SnapPy (3-manifold +# topology), not the compression lib. ore_algebra (D-finite guessing over +# Sage) has no PyPI release, so it is pinned by commit; its setup.py imports +# sage.env, so it must build WITHOUT pip's build isolation, against the env's +# own sage/cython/flint (hence --no-build-isolation and the env's setuptools). +ARG ORE_ALGEBRA_COMMIT=18680180c884fac869a064db99f29a221aad9dfe +RUN /opt/env/bin/pip install --no-cache-dir \ + python-sat==1.9.dev15 \ + cvc5==1.3.4 \ + ortools==9.15.6755 \ + snappy==3.3.2 \ + && PKG_CONFIG_PATH=/opt/env/lib/pkgconfig \ + /opt/env/bin/pip install --no-cache-dir --no-build-isolation \ + "ore_algebra @ git+https://github.com/mkauers/ore_algebra@${ORE_ALGEBRA_COMMIT}" \ + && find /opt/env -name '__pycache__' -type d -prune -exec rm -rf {} + + +# --------------------------------------------------------------------------- # +# solvers_build: tools with no conda-forge or bookworm packaging, built from # +# pinned sources (plus the pinned official cvc5 static binary -- its PyPI # +# wheel in compute_build carries only the python API). Everything lands in # +# /out/bin and links only libc/libm from the shared bookworm userland (flint/ # +# gmp/mpfr are linked statically), so the binaries drop straight into agent. # +# --------------------------------------------------------------------------- # +FROM debian:bookworm-slim AS solvers_build + +ENV DEBIAN_FRONTEND=noninteractive + +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl ca-certificates build-essential unzip m4 \ + libgmp-dev libmpfr-dev \ + && rm -rf /var/lib/apt/lists/* \ + && mkdir -p /out/bin + +# kissat: state-of-the-art CDCL SAT solver (DIMACS in/out). +ARG KISSAT_VERSION=rel-4.0.4 +RUN curl -sSfL "https://github.com/arminbiere/kissat/archive/refs/tags/${KISSAT_VERSION}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/kissat-* \ + && ./configure && make -j"$(nproc)" \ + && install -m 755 build/kissat /out/bin/kissat \ + && rm -rf /tmp/kissat-* + +# plantri: planar-graph generator (Brinkmann & McKay). +ARG PLANTRI_VERSION=55 +RUN curl -sSfL "https://users.cecs.anu.edu.au/~bdm/plantri/plantri${PLANTRI_VERSION}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/plantri* \ + && make plantri \ + && install -m 755 plantri /out/bin/plantri \ + && rm -rf /tmp/plantri* + +# prover9/mace4: first-order theorem prover + finite-model finder. Upstream +# (cs.unm.edu LADR-2009-11A) has no releases and Debian dropped the package; +# built from a pinned commit of the ai4reason mirror of that final release. +ARG PROVER9_COMMIT=cdca95a51d3c3459b8fd2ebbb5ac1504be2172e3 +RUN curl -sSfL "https://github.com/ai4reason/Prover9/archive/${PROVER9_COMMIT}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/Prover9-* \ + && make all \ + && install -m 755 bin/prover9 bin/mace4 bin/interpformat bin/prooftrans /out/bin/ \ + && rm -rf /tmp/Prover9-* + +# msolve: multivariate polynomial system solver (Groebner bases). Needs +# FLINT >= 3, which bookworm lacks -- both are built here, FLINT static so +# nothing but the msolve binaries ship. +ARG FLINT_VERSION=3.6.0 +ARG MSOLVE_VERSION=0.10.1 +RUN curl -sSfL "https://github.com/flintlib/flint/releases/download/v${FLINT_VERSION}/flint-${FLINT_VERSION}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/flint-* \ + && ./configure --disable-shared --prefix=/usr/local \ + && make -j"$(nproc)" && make install \ + && rm -rf /tmp/flint-* +RUN curl -sSfL "https://github.com/algebraic-solving/msolve/releases/download/v${MSOLVE_VERSION}/msolve-${MSOLVE_VERSION}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/msolve-* \ + && ./configure --disable-shared \ + && make -j"$(nproc)" \ + && install -m 755 msolve /out/bin/msolve \ + && rm -rf /tmp/msolve-* + +# cvc5: SMT solver, official pinned static release binary (matches the pip +# bindings' version in compute_build). +ARG CVC5_VERSION=1.3.4 +RUN arch="$(uname -m)" \ + && case "$arch" in x86_64) a=x86_64 ;; aarch64) a=arm64 ;; *) echo "unsupported arch $arch" >&2; exit 1 ;; esac \ + && curl -sSfL -o /tmp/cvc5.zip \ + "https://github.com/cvc5/cvc5/releases/download/cvc5-${CVC5_VERSION}/cvc5-Linux-${a}-static.zip" \ + && unzip -q /tmp/cvc5.zip -d /tmp/cvc5 \ + && install -m 755 /tmp/cvc5/*/bin/cvc5 /out/bin/cvc5 \ + && rm -rf /tmp/cvc5 /tmp/cvc5.zip + +# --------------------------------------------------------------------------- # +# loogle_build: the Loogle type-pattern Mathlib search CLI, the one pin-tied # +# addition to the agent's compute stack. Built FROM base so it compiles at # +# the PROJECT toolchain against the PROJECT's Mathlib rev (read from the # +# baked lake-manifest.json): the binary importModules-loads Mathlib oleans at # +# runtime, and the agent image reuses the FC project's own oleans via # +# LEAN_PATH (see the loogle wrapper in `agent`) rather than shipping a second # +# multi-GB Mathlib. The Loogle rev is chosen inside the pin's toolchain # +# window (its own lean-toolchain is overwritten with the project's, exactly # +# like lean4export_build). # +# --------------------------------------------------------------------------- # +FROM base AS loogle_build + +ARG LOOGLE_COMMIT=79343e3e37b64046e6b555936682012e80300df1 +RUN git clone https://github.com/nomeata/loogle.git /opt/loogle-src \ + && git -C /opt/loogle-src checkout --detach "${LOOGLE_COMMIT}" \ + && cd /opt/loogle-src \ + && cp /workspace/leanproject/lean-toolchain lean-toolchain \ + && MATHLIB_REV="$(python3 -c "import json; print(next(p['rev'] for p in json.load(open('/workspace/leanproject/lake-manifest.json'))['packages'] if p['name'] == 'mathlib'))")" \ + && sed -i "s|require mathlib from git \"https://github.com/leanprover-community/mathlib4\" @ \"master\"|require mathlib from git \"https://github.com/leanprover-community/mathlib4\" @ \"${MATHLIB_REV}\"|" lakefile.lean \ + && grep -q "@ \"${MATHLIB_REV}\"" lakefile.lean \ + && rm lake-manifest.json \ + && lake update \ + && lake exe cache get \ + && lake build loogle + +# Stage the runtime pieces: the binary plus loogle's own module oleans (its +# Mathlib/dependency oleans are NOT staged -- the agent image points LEAN_PATH +# at the FC project's baked packages, same toolchain and Mathlib rev by +# construction). +RUN mkdir -p /opt/loogle/bin \ + && cp /opt/loogle-src/.lake/build/bin/loogle /opt/loogle/bin/loogle \ + && cp -r /opt/loogle-src/.lake/build/lib/lean /opt/loogle/lib + +# --------------------------------------------------------------------------- # +# agent: the agent's workspace. Layer order is big/stable first (the conda # +# env), then apt, then the small solver binaries, then Loogle, then docs # +# (which churn most). # +# --------------------------------------------------------------------------- # +FROM base AS agent + +# The compute env (see compute-env.yaml). /opt/env/bin goes FIRST on PATH so +# the env's python IS the agent's `python3` (and sage, gp, gap, z3, ... all +# resolve there); the profile.d snippet covers login shells (`bash --login +# -c`, how apn.tools execs), the ENV covers plain execs. +COPY --from=compute_build /opt/env /opt/env +ENV PATH=/opt/env/bin:$PATH +RUN echo 'export PATH=/opt/env/bin:$PATH' > /etc/profile.d/compute-env.sh + +# Tools conda-forge lacks, from bookworm: polymake (polyhedral geometry), +# Macaulay2 (commutative algebra), regina-normal (low-dimensional topology; +# `regina-python`), cryptominisat (SAT, newer here than conda-forge's), +# coinor-csdp (semidefinite programming, `csdp`), jq + ripgrep for the bash +# tool (git is already in `base`), libmpfr6 (msolve's one non-static runtime +# link besides gmp, which base's libgmp-dev already provides). +RUN apt-get update && apt-get install -y --no-install-recommends \ + polymake macaulay2 regina-normal cryptominisat coinor-csdp \ + jq ripgrep libmpfr6 \ && rm -rf /var/lib/apt/lists/* +# Source-built solvers (kissat, plantri, prover9/mace4, msolve, cvc5). +COPY --from=solvers_build /out/bin/ /usr/local/bin/ + +# Loogle: binary + its own module oleans; Mathlib resolves from the FC +# project's baked packages via LEAN_PATH (same toolchain + Mathlib rev as the +# loogle_build stage by construction). The wrapper makes `loogle "..."` work +# without the agent knowing any of this. +COPY --from=loogle_build /opt/loogle /opt/loogle +RUN printf '%s\n' \ + '#!/bin/sh' \ + '# Loogle needs its own oleans plus the project Mathlib oleans on LEAN_PATH.' \ + 'LEAN_PATH=/opt/loogle/lib' \ + 'for d in /workspace/leanproject/.lake/packages/*/.lake/build/lib/lean; do' \ + ' LEAN_PATH="$LEAN_PATH:$d"' \ + 'done' \ + 'export LEAN_PATH' \ + 'exec /opt/loogle/bin/loogle "$@"' \ + > /usr/local/bin/loogle \ + && chmod 755 /usr/local/bin/loogle + +# In-sandbox references (the sandbox has no network): vendored, version-matched +# docs for the tools whose syntax the agent is unlikely to know cold. Last: +# docs churn more than any layer above. +COPY docs /opt/docs + CMD ["sleep", "infinity"] # --------------------------------------------------------------------------- # diff --git a/apn/lean/compute-env.yaml b/apn/lean/compute-env.yaml new file mode 100644 index 00000000..98b7c9c6 --- /dev/null +++ b/apn/lean/compute-env.yaml @@ -0,0 +1,52 @@ +# The agent's compute environment: one locked conda-forge env at /opt/env +# (created by the Dockerfile's `compute_build` stage; /opt/env/bin is first on +# the agent's PATH, so this env's python IS the agent's `python3`). +# +# Every tool the agent is promised is listed here EXPLICITLY with an exact +# pin, even where it would arrive anyway as a sage dependency (pari, gap, +# maxima, singular, ecm, nauty, ...): the roster must not depend on what sage +# happens to pull. Transitive dependencies not listed here resolve at image +# build time. Version bumps are deliberate edits to this file. The solve is +# verified for linux-64 and linux-aarch64 (local dev on Apple silicon); when +# bumping a pin, keep versions that exist for both platforms. +# +# pip-layer packages (python-sat, cvc5 bindings, ortools, snappy, ore_algebra) +# are installed into this same env by the Dockerfile, pinned there. +name: compute +channels: + - conda-forge +dependencies: + - python=3.13.15 + - pip=26.2.1 + - setuptools=84.0.0 # ore_algebra's no-isolation pip build needs it + # computer algebra systems and their engines + - sage=10.9 + - pari=2.17.3 # PARI/GP: the `gp` binary + libpari + - gap-defaults=4.15.1 # GAP: computational group theory + - maxima=5.49.0 + - singular=4.4.1.p5 + # python stack + - numpy=2.5.2 + - scipy=1.18.0 + - sympy=1.14.0 + - mpmath=1.4.1 + - pandas=3.0.5 + - networkx=3.6.1 + - python-igraph=0.11.9 + - python-flint=0.8.0 + - highspy=1.15.1 + # solvers (binary + python bindings) + - z3-solver=5.1.0.0 + - glpk=5.0 + # lattice reduction + - fpylll=0.6.4 + # number theory CLI tools + - primesieve=12.13 + - primecount=8.2 + - ecm=7.0.6 # GMP-ECM factorization + # graph / discrete geometry / algebra CLI tools + - nauty=2.9.3 + - cliquer=1.23 + - normaliz=3.11.0 + - 4ti2=1.6.15 + - lrslib=73.a diff --git a/apn/lean/pantograph-docs/LICENSE b/apn/lean/pantograph-docs/LICENSE deleted file mode 100644 index 34f63a39..00000000 --- a/apn/lean/pantograph-docs/LICENSE +++ /dev/null @@ -1,190 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - Copyright 2024 Leni Aniva - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/apn/lean/pantograph-docs/contributing.md b/apn/lean/pantograph-docs/contributing.md deleted file mode 100644 index 6d61d944..00000000 --- a/apn/lean/pantograph-docs/contributing.md +++ /dev/null @@ -1,42 +0,0 @@ -# Contributing - -A Lean development shell is provided in the Nix flake. Nix usage is optional. -Any contribution has to pass the pre-commit hooks, installable using either `prek` or `pre-commit`: -```sh -prek install -pre-commit install --install-hooks -``` - -All commit messages must conform to the Conventional Commits specification. - -## Testing - -The tests are based on `LSpec`. To run tests, use either - -``` sh -nix flake check -``` -or -``` sh -lake test -``` - -You can run an individual test by specifying a prefix - -``` sh -lake test -- Frontend/Collect -``` - -## Formatting - -When writing Lean code, follow the guidelines - -- Functions should be in `camelCase` -- Theorems and tests should be in `snake_case` -- Write the `|` in a pattern-matching `let` on the next line. This is for visual - distinction with long function arguments. -```lean -let .some result := function - | fail "incorrect" -``` -- Each test should be pinpointed and as devolatilized as possible. diff --git a/apn/lean/pantograph-docs/rationale.md b/apn/lean/pantograph-docs/rationale.md deleted file mode 100644 index d44b02a9..00000000 --- a/apn/lean/pantograph-docs/rationale.md +++ /dev/null @@ -1,60 +0,0 @@ -# Design Rationale - -A great problem in machine learning is to use ML agents to automatically prove -mathematical theorems. This sort of proof necessarily involves *search*. -Compatibility for search is the main reason for creating Pantograph. The Lean 4 -LSP interface is not conducive to search. Pantograph is designed with this in -mind. It emphasizes the difference between 3 views of a proof: - -- **Presentation View**: The view of a written, polished proof. e.g. Mathlib and - math papers are almost always written in this form. -- **Search View**: The view of a proof exploration trajectory. This is not - explicitly supported by Lean LSP. -- **Kernel View**: The proof viewed as a set of metavariables. - -Pantograph enables proof agents to operate on the search view. - -## Name - -The name Pantograph is a pun. It means two things -- A pantograph is an instrument for copying down writing. As an agent explores - the vast proof search space, Pantograph records the current state to ensure - the proof is sound. -- A pantograph is also an equipment for an electric train. It supplies power to - a locomotive. In comparison the (relatively) simple Pantograph software powers - theorem proving projects. - -## Caveats and Limitations - -Pantograph does not exactly mimic Lean LSP's behaviour. That would not grant the -flexibility it offers. To support tree search means Pantograph has to act -differently from Lean in some times, but never at the sacrifice of soundness. - -- When Lean LSP says "don't know how to synthesize placeholder", this indicates - the human operator needs to manually move the cursor to the placeholder and - type in the correct expression. This error therefore should not halt the proof - process, and the placeholder should be turned into a goal. -- When Lean LSP says "unresolved goals", that means a proof cannot finish where - it is supposed to finish at the end of a `by` block. Pantograph will raise the - error in this case, since it indicates the termination of a proof search branch. - -Pantograph cannot perform things that are inherently constrained by Lean. These -include: - -- If a tactic loses track of metavariables, it will not be caught until the end - of the proof search. This is a bug in the tactic itself. -- Although a timeout feature exists in Pantograph, it relies on the coöperative - multitasking from the tactic implementation. There is nothing preventing a - buggy tactic from stalling Lean if it does not check for cancellation often. -- For the same reason as above, there is no graceful way to stop a tactic which - leaks infinite memory. Users who wish to have this behaviour should run - Pantograph in a controlled environment with limited allocations. e.g. - Linux control groups. -- Interceptions of parsing errors generally cannot be turned into goals (e.g. - `def mystery : Nat := :=`) due to Lean's parsing system. This question is also - not well-defined. - -## References - -* [Pantograph Paper](https://arxiv.org/abs/2410.16429) - diff --git a/apn/lean/pantograph-docs/repl.md b/apn/lean/pantograph-docs/repl.md deleted file mode 100644 index 0498f5f6..00000000 --- a/apn/lean/pantograph-docs/repl.md +++ /dev/null @@ -1,192 +0,0 @@ -# REPL - -This documentation is about interacting with the REPL. - -## Examples - -After building the `repl`, it will be available in `.lake/build/bin/repl`. -Execute it by either directly referring to its name, or `lake exe repl`. - -``` sh -repl MODULES|LEAN_OPTIONS -``` - -The `repl` executable must be given with a list of modules to import. By default -it will import nothing, not even `Init`. It can also accept lean options of the -form `--key=value` e.g. `--pp.raw=true`. - -Running repl with `--version` shows the version and then exits. - -After it emits the `ready.` signal, `repl` accepts commands as single-line JSON -inputs and outputs either an `Error:` (indicating malformed command) or a JSON -return value indicating the result of a command execution. The command must be -given in one of two formats - -``` -command { ... } -{ "cmd": command, "payload": ... } -``` - -The list of available commands can be found below. An empty command aborts the -REPL. - -Example: (~5k symbols) -``` -$ repl Init -env.catalog {} -env.inspect {"name": "Nat.le_add_left"} -``` - -Example with `mathlib4` (~90k symbols, may stack overflow, see troubleshooting) - -``` -$ repl Mathlib.Analysis.Seminorm -env.catalog {} -``` - -Example proving a theorem: (alternatively use `goal.start {"copyFrom": "Nat.add_comm"}`) -to prime the proof - -``` -$ repl Init -goal.start {"expr": "∀ (n m : Nat), n + m = m + n"} -goal.tactic {"stateId": 0, "tactic": "intro n m"} -goal.tactic {"stateId": 1, "tactic": "assumption"} -goal.delete {"stateIds": [0]} -stat {} -goal.tactic {"stateId": 1, "tactic": "rw [Nat.add_comm]"} -stat -``` -where the application of `assumption` should lead to a failure. - -### Project Environment - -To use Pantograph in a project environment, setup the `LEAN_PATH` environment -variable so it contains the library path of lean libraries. The libraries must -be built in advance. For example, if `mathlib4` is stored at `../lib/mathlib4`, -the environment might be setup like this: - -``` sh -LIB="../lib" -LIB_MATHLIB="$LIB/mathlib4/.lake" -export LEAN_PATH="$LIB_MATHLIB:$LIB_MATHLIB/aesop/build/lib:$LIB_MATHLIB/Qq/build/lib:$LIB_MATHLIB/std/build/lib" - -LEAN_PATH=$LEAN_PATH repl $@ -``` -The `$LEAN_PATH` executable of any project can be extracted by -``` sh -lake env printenv LEAN_PATH -``` - -Additional modules cannot be imported after the perennial process starts, either -via `env.load` or the frontend functions. The technical reason for this is when -Lean cannot determine whether an imported module's initializer has run. - -## Commands - -See `Pantograph/Protocol.lean` for a description of the parameters and return values in JSON. -* `reset`: Delete all cached expressions and proof trees -* `stat`: Display resource usage -* `options.set { key: value, ... }`: Set one or more options. These are not Lean - `CoreM` options; those have to be set via command line arguments.), for - options see below. -* `options.print`: Display the current set of options -* `expr.echo {"expr": , "type": , ["levels": []]}`: Determine the - type of an expression and format it. -* `env.catalog`: Display a list of all safe Lean symbols in the current environment -* `env.inspect {"name": , "value": }`: Show the type and package of a - given symbol; If value flag is set, the value is printed or hidden. By default - only the values of definitions are printed. -* `env.save { "path": }`, `env.load { "path": }`: Save/Load the - current environment to/from a file -* `env.module_read { "module": }`: Reads a list of symbols from a module -* `env.describe {}`: Describes the imports and modules in the current environment -* `env.parse { "input": , "category": }`: Parse a bit - of syntax and returns the parser's terminal position. -* `goal.start {["name": ], ["expr": ], ["levels": []], ["copyFrom": ]}`: - Start a new proof from a given expression or symbol -* `goal.tactic {"stateId": , ["goalId": ], ["autoResume": ], ...}`: - Execute a tactic string on a given goal site. The tactic is supplied as additional - key-value pairs in one of the following formats: - - `{ "tactic": }`: Executes a tactic or a sequence of tactics in the - current mode. - - `{ "mode": }`: Enter a different tactic mode. The permitted values - are `tactic` (default), `conv`, `calc`. In case of `calc`, each step must - be of the form `lhs op rhs`. An `lhs` of `_` indicates that it should be set - to the previous `rhs`. - - `{ "expr": }`: Assign the given proof term to the current goal - - `{ "have": , "binderName": }`: Execute `have` and creates a branch goal - - `{ "let": , "binderName": }`: Execute `let` and creates a branch goal - - `{ "draft": }`: Draft an expression with `sorry`s, turning them into - goals. Coupling is not allowed. - If the `goals` field does not exist, the tactic execution has failed. Read - `messages` to find the reason. -* `goal.continue {"stateId": , ["branch": ], ["goals": ]}`: - Execute continuation/resumption - - `{ "branch": }`: Continue on branch state. The current state must have no goals. - - `{ "goals": }`: Resume the given goals -* `goal.subsume {"stateId": , "goal": , "candidates": - , ["srcStateId": ]}`: determine if any goal in `candidates` (coming - from either the provided state id or `srcStateId`) subsumes `goal`. It returns - the *subsumptor* (goal providing the solution) and a new state id if the - subsumption is not a cycle, in which case the *subsumend* `goal` is erased. -* `goal.remove {"stateIds": []}"`: Drop the goal states specified in the list -* `goal.print {"stateId": }"`: Print a goal state -* `goal.save { "id": , "path": }`, `goal.load { "path": }`: - Save/Load a goal state to/from a file. The environment is not carried with the - state. The user is responsible to ensure the sender/receiver instances share - the same environment. -* `frontend.process { ["fileName": ,] ["file": ], readHeader: - , inheritEnv: , invocations: , newConstants: }`: - Executes the Lean frontend on a file, collecting the tactic invocations - (`"invocations": output-path`), or new constants (`newConstants`) -* `frontend.distil { "file": , ["binderName": ], "ignoreValues": bool - }`: Extract condensed search targets from a file, where coupled search targets - will be condensed into one. Set `binderName` to override the binder name to - e.g. `f`. Set `ignoreValues` to false to incorporate existing solutions. - - Note that `example`s are not search targets! -* `frontend.track { "src": , "dst": }`: Check if one file conforms to - another. The declarations in `src` could have `sorry`s and the declarations in - `dst` would fill them. -* [Experimental] `frontend.refactor { "file": , "coreOptions": - [["="]] }`: Group dependent `sorry`s into one single `sorry`. - Currently only flat dependencies are supported (i.e. an object with a list of - properties). - -## Options - -The full list of options can be found in `Pantograph/Protocol.lean`. Particularly: -- `automaticMode` (default on): Goals will not become dormant when this is - turned on. By default it is turned on, with all goals automatically resuming. - This makes Pantograph act like a gym, with no resumption necessary to manage - your goals. -- `timeout` (default 0): Set `timeout` to a non-zero number to specify timeout - (milliseconds) for all `CoreM` and frontend operations. - -## Errors - -When an error pertaining to the execution of a command happens, the returning JSON structure is - -``` json -{ "error": "type", "desc": "description" } -``` -Common error forms: -* `command`: Indicates malformed command structure which results from either - invalid command or a malformed JSON structure that cannot be fed to an - individual command. -* `index`: Indicates an invariant maintained by the output of one command and - input of another is broken. For example, attempting to query a symbol not - existing in the library or indexing into a non-existent proof state. -* `parse`: Indicates parsing errors -* `elab`: Indicates elaboration errors -* `frontend`: Indicates whole-file parsing and elaboration errors -* `io`: Generic IO error -* `command`: The command's argument is malformed - -## Troubleshooting - -If lean encounters stack overflow problems when printing catalog, execute this before running lean: -```sh -ulimit -s unlimited -``` diff --git a/apn/lean/pypantograph-docs/LICENSE b/apn/lean/pypantograph-docs/LICENSE deleted file mode 100644 index 34f63a39..00000000 --- a/apn/lean/pypantograph-docs/LICENSE +++ /dev/null @@ -1,190 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - Copyright 2024 Leni Aniva - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/apn/lean/pypantograph-docs/agent-search.md b/apn/lean/pypantograph-docs/agent-search.md deleted file mode 100644 index e640b4a4..00000000 --- a/apn/lean/pypantograph-docs/agent-search.md +++ /dev/null @@ -1,81 +0,0 @@ - - -# Search - -Pantograph supports basic proof search. In this case, Pantograph treats goals as nodes on an and-or tree. The user supplies an agent which should provide two functions: - -1. *Tactic*: Which tactic should be used on a goal? -2. *Guidance*: What is the search priority on a goal? - -The user agent should inherit from `pantograph.search.Agent`. Here is a brute force agent example: - -```python -from typing import Optional -import collections -from pantograph import Server -from pantograph.search import Agent -from pantograph.expr import GoalState, Tactic -``` - -```python -class DumbAgent(Agent): - - def __init__(self): - super().__init__() - - self.goal_tactic_id_map = collections.defaultdict(lambda : 0) - self.intros = [ - "intro", - ] - self.tactics = [ - "intro h", - "cases h", - "apply Or.inl", - "apply Or.inr", - ] - self.no_space_tactics = [ - "assumption", - ] - - def next_tactic( - self, - state: GoalState, - goal_id: int, - ) -> Optional[Tactic]: - key = (state.state_id, goal_id) - i = self.goal_tactic_id_map[key] - - target = state.goals[goal_id].target - if target.startswith('∀'): - tactics = self.intros - elif ' ' in target: - tactics = self.tactics - else: - tactics = self.no_space_tactics - - if i >= len(tactics): - return None - - self.goal_tactic_id_map[key] = i + 1 - return tactics[i] -``` - -Execute the search with `agent.search`. - -```python -server = Server() -agent = DumbAgent() -goal_state = server.goal_start("∀ (p q: Prop), Or p q -> Or q p") -agent.search(server=server, goal_state=goal_state, verbose=False) -``` - -Output: -``` -SearchResult(n_goals_root=1, duration=0.7717759609222412, success=True, steps=16) -``` - -## Automatic and Manual Modes - -The agent chooses one goal and executes a tactic on this goal. What happens to the other goals that are not chosen? By default, the server runs in automatic mode. In automatic mode, all other goals are automatically inherited by a child state, so a user agent could declare a proof finished when there are no more goals remaining in the current goal state. - -Some users may wish to handle sibling goals manually. For example, Aesop's treatment of metavariable coupling is not automatic. To do this, pass the flag `options={ "automaticMode" : False }` to the `Server` constructor. diff --git a/apn/lean/pypantograph-docs/examples/README.md b/apn/lean/pypantograph-docs/examples/README.md deleted file mode 100644 index f03db11e..00000000 --- a/apn/lean/pypantograph-docs/examples/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Examples - -This example showcases how to bind library dependencies and execute the `Aesop` -tactic in Lean. First build the example project: -``` sh -pushd Example -lake build -popd -``` -This would generate compiled `.olean` files. Then run one of the examples from the -project root: -``` sh -poetry run examples/aesop.py -poetry run examples/sketch.py -``` - -Warning: If you make modifications to any Lean files, you must re-run `lake -build`! Moreover, the version of the Lean used in the example folder (including -dependencies in `lakefile.lean` and `lean-toolchain`) **must match exactly** -with the version in `src/`! - -* `aesop.py`: Example of how to use the `aesop` tactic -* `sketch.py`: Example of loading a sketch - diff --git a/apn/lean/pypantograph-docs/examples/aesop.py b/apn/lean/pypantograph-docs/examples/aesop.py deleted file mode 100644 index b502ddfc..00000000 --- a/apn/lean/pypantograph-docs/examples/aesop.py +++ /dev/null @@ -1,14 +0,0 @@ -#!/usr/bin/env python3 - -from pathlib import Path -from pantograph.server import Server - -# This example shows how to use project dependencies - -if __name__ == '__main__': - project_path = Path(__file__).parent.resolve() / 'Example' - print(f"$PWD: {project_path}") - server = Server(imports=['Example'], project_path=project_path) - state0 = server.goal_start("forall (p q: Prop), Or p q -> Or q p") - state1 = server.goal_tactic(state0, tactic="aesop") - assert state1.is_solved diff --git a/apn/lean/pypantograph-docs/examples/branch-sorry.py b/apn/lean/pypantograph-docs/examples/branch-sorry.py deleted file mode 100644 index 0187c183..00000000 --- a/apn/lean/pypantograph-docs/examples/branch-sorry.py +++ /dev/null @@ -1,13 +0,0 @@ -#!/usr/bin/env python3 - -from pantograph.server import Server -from pantograph.expr import TacticHave - -# This example shows what happens when a tactic generates a sorry. -if __name__ == '__main__': - server = Server(imports=['Init']) - state0 = server.goal_start("1 = 0") - state1 = server.goal_tactic(state0, tactic=TacticHave("1 = 0")) - print(state1) - state1b = server.goal_tactic(state1, tactic="apply?") - print(state1b) diff --git a/apn/lean/pypantograph-docs/examples/simple.py b/apn/lean/pypantograph-docs/examples/simple.py deleted file mode 100644 index cbd5328b..00000000 --- a/apn/lean/pypantograph-docs/examples/simple.py +++ /dev/null @@ -1,7 +0,0 @@ -from pantograph.server import Server - -if __name__ == '__main__': - server = Server(imports=['Init']) - state0 = server.goal_start("forall (p q: Prop), Or p q -> Or q p") - state1 = server.goal_tactic(state0, tactic="intro") - print(state1) diff --git a/apn/lean/pypantograph-docs/examples/sketch.py b/apn/lean/pypantograph-docs/examples/sketch.py deleted file mode 100644 index eeaa0a4c..00000000 --- a/apn/lean/pypantograph-docs/examples/sketch.py +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/env python3 - -from pantograph.server import Server -from pantograph.expr import TacticDraft - -root = """ -theorem add_comm_proved_formal_sketch : ∀ n m : Nat, n + m = m + n := sorry -""" - -sketch = """ -by - -- Consider some n and m in Nats. - intros n m - -- Perform induction on n. - induction n with - | zero => - sorry - | succ n ih => - -- Inductive step: Assume n + m = m + n, we need to show succ n + m = m + succ n. - -- By the inductive hypothesis, we have n + m = m + n. - have h_inductive: n + m = m + n := sorry - -- 1. Note we start with: Nat.succ n + m = m + Nat.succ n, so, pull the succ out from m + Nat.succ n on the right side from the addition using addition facts Nat.add_succ. - have h_pull_succ_out_from_right: m + Nat.succ n = Nat.succ (m + n) := sorry - -- 2. then to flip m + S n to something like S (n + m) we need to use the IH. - have h_flip_n_plus_m: Nat.succ (n + m) = Nat.succ (m + n) := sorry - -- 3. Now the n & m are on the correct sides Nat.succ n + m = Nat.succ (n + m), so let's use the def of addition to pull out the succ from the addition on the left using Nat.succ_add. - have h_pull_succ_out_from_left: Nat.succ n + m = Nat.succ (n + m) := sorry - -- Combine facts to close goal - sorry -""" - -if __name__ == '__main__': - server = Server() - unit, = server.load_sorry(root) - print(unit.goal_state) - - # Send the draft payload using `TacticDraft` - state1 = server.goal_tactic( - unit.goal_state, - tactic=TacticDraft(sketch)) - print(state1) diff --git a/apn/lean/pypantograph-docs/frontend.md b/apn/lean/pypantograph-docs/frontend.md deleted file mode 100644 index 0d8f75ee..00000000 --- a/apn/lean/pypantograph-docs/frontend.md +++ /dev/null @@ -1,234 +0,0 @@ - - -# Data Extraction - -```python -import os -from pathlib import Path -from pantograph.server import Server -``` - -## Tactic Invocation - -Pantograph can extract tactic invocation data from a Lean file. A **tactic -invocation** is a tuple containing the before and after goal states, and the -tactic which converts the "before" state to the "after" state. - -To extract tactic invocation data, use `server.tactic_invocations(file_name)` -and supply the file name of the input Lean file. - -```python -project_path = Path(os.getcwd()).parent.resolve() / 'examples/Example' -print(f"$PWD: {project_path}") -server = await Server.create(imports=['Example'], project_path=project_path) -units = await server.tactic_invocations_async(project_path / "Example.lean") -``` - -Output: -``` -$PWD: /Users/aniva/Projects/matp/PyPantograph/examples/Example -``` - -The function returns a list of `CompilationUnit` objects, corresponding to each compilation unit in the input Lean file. For performance reasons only the text boundaries are loaded into `CompilationUnit`s. - -```python -with open(project_path / "Example.lean", 'rb') as f: - content = f.read() - for i, unit in enumerate(units): - print(f"#{i}: [{unit.i_begin},{unit.i_end}]") - unit_text = content[unit.i_begin:unit.i_end].decode('utf-8') - print(unit_text) -``` - -Output: -``` -#0: [14,85] -/-- Ensure that Aesop is running -/ -example : α → α := - by aesop - - -#1: [85,254] -example : ∀ (p q: Prop), p ∨ q → q ∨ p := by - intro p q h - -- Here are some comments - cases h - . apply Or.inr - assumption - . apply Or.inl - assumption -``` - -Each `CompilationUnit` includes a list of `TacticInvocation`s, which contains the `.before` (corresponding to the state before the tactic), `.after` (corresponding to the state after the tactic), and `.tactic` (tactic executed) fields. - -```python -for i in units[0].invocations: - print(f"[Before]\n{i.before}") - print(f"[Tactic]\n{i.tactic} (using {i.used_constants})") - print(f"[After]\n{i.after}") -``` - -Output: -``` -[Before] -α : Sort ?u.7 -⊢ α → α -[Tactic] -aesop (using []) -[After] -``` - -```python -for i in units[1].invocations: - print(f"[Before]\n{i.before}") - print(f"[Tactic]\n{i.tactic} (using {i.used_constants})") - print(f"[After]\n{i.after}") -``` - -Output: -``` -[Before] -⊢ ∀ (p q : Prop), p ∨ q → q ∨ p -[Tactic] -intro p q h (using []) -[After] -p q : Prop -h : p ∨ q -⊢ q ∨ p -[Before] -p q : Prop -h : p ∨ q -⊢ q ∨ p -[Tactic] -cases h (using ['Eq.refl', 'Or']) -[After] -case inl -p q : Prop -h✝ : p -⊢ q ∨ p -case inr -p q : Prop -h✝ : q -⊢ q ∨ p -[Before] -case inl -p q : Prop -h✝ : p -⊢ q ∨ p -[Tactic] -apply Or.inr (using ['Or.inr']) -[After] -case inl.h -p q : Prop -h✝ : p -⊢ p -[Before] -case inl.h -p q : Prop -h✝ : p -⊢ p -[Tactic] -assumption (using []) -[After] - -[Before] -case inr -p q : Prop -h✝ : q -⊢ q ∨ p -[Tactic] -apply Or.inl (using ['Or.inl']) -[After] -case inr.h -p q : Prop -h✝ : q -⊢ q -[Before] -case inr.h -p q : Prop -h✝ : q -⊢ q -[Tactic] -assumption (using []) -[After] -``` - -## Check Compilation - -Use `check_compile` to check if some Lean code compiles. - -Keep in mind that Lean compilation can execute arbitrary code. - -```python -server = await Server.create() -code = """ -example : 1 + 1 = 2 := by rfl -""" -await server.check_compile_async(code) -``` - -Output: -``` -[CompilationUnit(i_begin=0, i_end=31, messages=[], invocations=None, goal_state=None, goal_src_boundaries=None, new_constants=None)] -``` - -If there are no error messages, it means the unit compiles. - -## Loading Definitions - -Pantograph keeps track of a global environment. `Server.load_definitions` adds new definitions to the environment. - -```python -code = """ -def mystery : Nat -> Nat := fun x => x + 1 -""" -await server.load_definitions_async(code) -await server.env_inspect_async("mystery") -``` - -Output: -``` -{'type': {'pp': 'Nat → Nat'}, - 'sourceStart': {'line': 2, 'column': 0}, - 'sourceEnd': {'line': 2, 'column': 42}, - 'isUnsafe': False} -``` - -## Track Checking - -We can check if one file conforms to the definition and theorems of another. If the result object has no `failure`s or error messages, the check has passed. - -```python -src = """ -def f : Nat -> Nat := sorry -theorem property (n : Nat) : f n = n + 1 := sorry -""" -dst = """ -def f (x : Nat) := x + 1 -theorem property (n : Nat) : f n = n + 1 := rfl -""" -await server.check_track_async(src, dst) -``` - -Output: -``` -CheckTrackResult(src_messages=[], dst_messages=[], failure=None) -``` - -```python -src = """ -def f : Nat -> Nat := sorry -theorem property (n : Nat) : f n = n + 1 := sorry -""" -# Tampering! -dst = """ -def f (x : Nat) := x + 1 -theorem property (n : Nat) : 0 = 0 := rfl -""" -await server.check_track_async(src, dst) -``` - -Output: -``` -CheckTrackResult(src_messages=[], dst_messages=[], failure='Type clash of property') -``` diff --git a/apn/lean/pypantograph-docs/goal.md b/apn/lean/pypantograph-docs/goal.md deleted file mode 100644 index 489d8f05..00000000 --- a/apn/lean/pypantograph-docs/goal.md +++ /dev/null @@ -1,370 +0,0 @@ - - -# Goals and Tactics - -Executing tactics in Pantograph is simple. To start a proof, call the -`Server.goal_start` function and supply an expression. - -```python -from pantograph import Server -from pantograph.expr import Site, TacticHave, TacticExpr, TacticMode -``` - -```python -server = await Server.create() -state0 = await server.goal_start_async("forall (p q: Prop), Or p q -> Or q p") -``` - -This creates a *goal state*, which consists of some goals. In this -case since it is the beginning of a state, it has only one goal. - -```python -print(state0) -``` - -Output: -``` - -⊢ forall (p q: Prop), Or p q -> Or q p -``` - -To execute a tactic on a goal state, use `Server.goal_tactic`. This function -takes a state, a tactic, and an optional site (see below). Most Lean tactics are strings. - -```python -state1 = await server.goal_tactic_async(state0, "intro a") -print(state1) -``` - -Output: -``` -a : Prop -⊢ ∀ (q : Prop), a ∨ q → q ∨ a -``` - -Executing a tactic produces a new goal state. If this goal state has no goals, -the proof is complete. You can recover the usual form of a goal with `str()` - -```python -print(state1.goals[0]) -``` - -Output: -``` -a : Prop -⊢ ∀ (q : Prop), a ∨ q → q ∨ a -``` - -Starting in v0.3.5, you can run multiple tactics in one shot. Use `?_` to mark goals to be solved later. - -```python -state2 = await server.goal_tactic_async(state0, "intro p q\nintro h\ncases h") -print(state2) -``` - -Output: -``` -inl -p : Prop -q : Prop -h✝ : p -⊢ q ∨ p -inr -p : Prop -q : Prop -h✝ : q -⊢ q ∨ p -``` - -```python -state2 = await server.goal_tactic_async(state0, "intro p q h\nhave random : 1 + 1 = 2 := ?_\ncases h") -print(state2) -``` - -Output: -``` -refine_2.inl -p : Prop -q : Prop -random : 1 + 1 = 2 -h✝ : p -⊢ q ∨ p -refine_2.inr -p : Prop -q : Prop -random : 1 + 1 = 2 -h✝ : q -⊢ q ∨ p -refine_1 -p : Prop -q : Prop -h : p ∨ q -⊢ 1 + 1 = 2 -``` - -## Error Handling and GC - -When a tactic fails, it throws an exception (`TacticFailure`) which contains a list of either `str`s or `Message` objects in `e.args[0]`. - -```python -from pantograph.message import TacticFailure -try: - state2 = await server.goal_tactic_async(state1, "assumption") - print("Should not reach this") -except TacticFailure as e: - print(e) - for msg in e.args[0]: - print(msg) -``` - -Output: -``` -[Message(data="tactic 'assumption' failed\na : Prop\n⊢ ∀ (q : Prop), a ∨ q → q ∨ a", pos=Position(line=0, column=0), pos_end=None, severity=, kind=None)] -0:0: error: tactic 'assumption' failed -a : Prop -⊢ ∀ (q : Prop), a ∨ q → q ∨ a -``` - -A state with no goals is considered solved - -```python -state0 = await server.goal_start_async("forall (p : Prop), p -> p") -state1 = await server.goal_tactic_async(state0, "intro") -state2 = await server.goal_tactic_async(state1, "intro h") -state3 = await server.goal_tactic_async(state2, "exact h") -state3 -``` - -Output: -``` -GoalState(#7, goals=[], _sentinel=#4 -``` - -Execute `server.gc()` once in a while to delete unused goals. - -```python -await server.gc_async() -``` - -## Special Tactics - -Lean has special provisions for some tactics. This includes `have`, `let`, -`calc`. To execute one of these tactics, create a `TacticHave`, `TacticLet`, -instance and feed it into `server.goal_tactic`. - -Technically speaking `have` and `let` are not tactics in Lean, so their execution requires special attention. In v0.3.5, they can be run under the normal tactic function as well (see above). - -```python -state0 = await server.goal_start_async("1 + 1 = 2") -state1 = await server.goal_tactic_async(state0, TacticHave(branch="2 = 1 + 1", binder_name="h")) -print(state1) -``` - -Output: -``` - -⊢ 2 = 1 + 1 -h : 2 = 1 + 1 -⊢ 1 + 1 = 2 -``` - -The `TacticExpr` "tactic" parses an expression and assigns it to the current -goal. This leverages Lean's type unification system and is as expressive as -Lean expressions. Many proofs in Mathlib4 are written in a mixture of expression -and tactic forms. - -```python -state0 = await server.goal_start_async("forall (p : Prop), p -> p") -state1 = await server.goal_tactic_async(state0, "intro p") -state2 = await server.goal_tactic_async(state1, TacticExpr("fun h => h")) -print(state2) -``` - -Output: -``` - -``` - -### Drafting - -Pantograph supports drafting (technically the sketch step) from -[Draft-Sketch-Prove](https://github.com/wellecks/ntptutorial/tree/main/partII_dsp). -Pantograph's drafting feature is more powerful. At any place in the proof, you -can replace an expression with `sorry`, and the `sorry` will become a goal. Any type errors will also become goals. In order to detect whether type errors have occurred, the user can look at the messages from each compilation unit. - -At this point we must introduce the idea of compilation units. Each Lean -definition, theorem, constant, etc., is a *compilation unit*. When Pantograph -extracts data from Lean source code, it sections the data into these compilation -units. - -For example, consider this sketch produced by a language model prover: -```lean -by - intros n m - induction n with - | zero => - have h_base: 0 + m = m := sorry - have h_symm: m + 0 = m := sorry - sorry - | succ n ih => - have h_inductive: n + m = m + n := sorry - have h_pull_succ_out_from_right: m + Nat.succ n = Nat.succ (m + n) := sorry - have h_flip_n_plus_m: Nat.succ (n + m) = Nat.succ (m + n) := sorry - have h_pull_succ_out_from_left: Nat.succ n + m = Nat.succ (n + m) := sorry - sorry -``` -There are some `sorry`s that we want to solve automatically with hammer tactics. We can do this by drafting. - -Pantograph can also load `sorry`s from a code snippet, which provides an alternative way for proof initiation. Warning: `load_sorry` does not work with `example` declarations. - -```python -sketch = """ -theorem add_comm_proved_formal_sketch : ∀ n m : Nat, n + m = m + n := sorry -""" -unit, = await server.load_sorry_async(sketch) -print(unit.goal_state) -``` - -Output: -``` - -⊢ ∀ (n m : Nat), n + m = m + n -``` - -```python -step = """ -by - -- Consider some n and m in Nats. - intros n m - -- Perform induction on n. - induction n with - | zero => - -- Base case: When n = 0, we need to show 0 + m = m + 0. - -- We have the fact 0 + m = m by the definition of addition. - have h_base: 0 + m = m := sorry - -- We also have the fact m + 0 = m by the definition of addition. - have h_symm: m + 0 = m := sorry - -- Combine facts to close goal - sorry - | succ n ih => - sorry -""" -from pantograph.expr import TacticDraft -tactic = TacticDraft(step) -state1 = await server.goal_tactic_async(unit.goal_state, tactic) -print(state1) -``` - -Output: -``` -n : Nat -m : Nat -⊢ 0 + m = m -n : Nat -m : Nat -h_base : 0 + m = m -⊢ m + 0 = m -n : Nat -m : Nat -h_base : 0 + m = m -h_symm : m + 0 = m -⊢ 0 + m = m + 0 -n✝ : Nat -m : Nat -n : Nat -ih : n + m = m + n -⊢ n + 1 + m = m + (n + 1) -``` - -### Search Target Distillation - -Sometimes, we want to search for an object (witness) along with proofs (companions) of properties about the object. This problem is known as **companion generation**. In Pantograph, `load_sorry` will automatically pair companions to create coupled search targets. Note that this is only available for flat dependency structures, where one object has a list of properties. - -```python -sketch = """ -def f : Nat -> Nat := sorry -theorem property (n : Nat) : f n = n + 1 := sorry -""" -target, = await server.load_sorry_async(sketch, ignore_values=True) -print(target.goal_state) -``` - -Output: -``` - -⊢ { f // ∀ (n : Nat), f n = n + 1 } -``` - -## Sites - -The optional `site` argument to `goal_tactic` controls the area of effect of a tactic. Site controls what the tactic sees when it asks Lean for the current goal. Most tactics only act on a single goal, but tactics acting on multiple goals are plausible as well. - -The `auto_resume` field defaults to the server option's `automaticMode` (which defaults to `True`). When this field is true, Pantograph will not deliberately hide other goals away from the tactic. This is the usual modus operandi of tactic proofs in Lean. When `auto_resume` is set to `False`, Pantograph will set other goals to dormant. This can be useful in limiting the area of effect of a tactic. However, dormanting a goal comes with the extra burden that it has to be activated ("resume") later, via `goal_resume`. - -```python -state = await server.goal_start_async("forall (p : Prop), p -> And p (Or p p)") -state = await server.goal_tactic_async(state, "intro p h") -state = await server.goal_tactic_async(state, "apply And.intro") -print(state) -``` - -Output: -``` -left -p : Prop -h : p -⊢ p -right -p : Prop -h : p -⊢ p ∨ p -``` - -In the example below, we set `auto_resume` to `False`, and the sibling goal is dormanted. - -```python -state1 = await server.goal_tactic_async(state, "exact h", site=Site(goal_id=0, auto_resume=False)) -print(state1) -``` - -Output: -``` - -``` - -In the example below, we preferentially operate on the second goal. Note that the first goal is still here. - -```python -state2 = await server.goal_tactic_async(state, "apply Or.inl", site=Site(goal_id=1)) -print(state2) -``` - -Output: -``` -right.h -p : Prop -h : p -⊢ p -left -p : Prop -h : p -⊢ p -``` - -## Tactic Modes - -Pantograph has special provisions for handling `conv` and `calc` tactics. The commonality of these tactics is incremental feedback: The tactic can run half way and produce some goal. Pantograph supports this via tactic modes. Every goal carries around with it a `TacticMode`, and the user is free to switch between modes. By default, the mode is `TacticMode.TACTIC`. - -```python -state = await server.goal_start_async("∀ (a b: Nat), (b = 2) -> 1 + a + 1 = a + b") - -state = await server.goal_tactic_async(state, "intro a b h") -state = await server.goal_tactic_async(state, TacticMode.CALC) -state = await server.goal_tactic_async(state, "1 + a + 1 = a + 1 + 1") -state -``` - -Output: -``` -GoalState(#24, goals=[Goal(id='_uniq.381', variables=[Variable(t='Nat', v=None, name='a'), Variable(t='Nat', v=None, name='b'), Variable(t='b = 2', v=None, name='h')], target='1 + a + 1 = a + 1 + 1', sibling_dep=None, name='calc', mode=), Goal(id='_uniq.400', variables=[Variable(t='Nat', v=None, name='a'), Variable(t='Nat', v=None, name='b'), Variable(t='b = 2', v=None, name='h')], target='a + 1 + 1 = a + b', sibling_dep=None, name=None, mode=)], _sentinel=#14 -``` diff --git a/apn/lean/pypantograph-docs/intro.md b/apn/lean/pypantograph-docs/intro.md deleted file mode 100644 index 0d257bcc..00000000 --- a/apn/lean/pypantograph-docs/intro.md +++ /dev/null @@ -1,79 +0,0 @@ -# Introduction - -This is Pantograph, an machine-to-machine interaction interface for Lean 4. -Its main purpose is to train and evaluate theorem proving agents. The main -features of Pantograph are: - -1. Writing mixed expression and tactic style proofs -2. Exposing the minimum amount of information for a search agent -3. Handling of metavariable coupling -4. Reading/Adding symbols from the environment -5. Extraction of tactic training data -6. Drafting incomplete proofs - -## Name - -The name Pantograph is a pun. It means two things -- A pantograph is an instrument for copying down writing. As an agent explores - the vast proof search space, Pantograph records the current state to ensure - the proof is sound. -- A pantograph is also an equipment for an electric train. It supplies power to - a locomotive. In comparison the (relatively) simple Pantograph software powers - theorem proving projects. - -## Design Rationale - -The Lean 4 interface is not conducive to search. Readers familiar with Coq may -know that the Coq Serapi was superseded by CoqLSP. In the opinion of the -authors, this is a mistake. An interface conducive for human operators to write -proofs is often not an interface conductive to machine learning agents for -searching. - -All of Pantograph's business logic is written in Lean, allowing coupling between -the data extraction and proof search components. - -## Caveats and Limitations - -Pantograph does not exactly mimic Lean LSP's behaviour. That would not grant the -flexibility it offers. To support tree search means Pantograph has to act -differently from Lean in some times, but never at the sacrifice of soundness. - -- When Lean LSP says "don't know how to synthesize placeholder", this indicates - the human operator needs to manually move the cursor to the placeholder and - type in the correct expression. This error therefore should not halt the proof - process, and the placeholder should be turned into a goal. -- When Lean LSP says "unresolved goals", that means a proof cannot finish where - it is supposed to finish at the end of a `by` block. Pantograph will raise the - error in this case, since it indicates the termination of a proof search branch. - -Pantograph cannot perform things that are inherently constrained by Lean. These -include: - -- If a tactic loses track of metavariables, it will not be caught until the end - of the proof search. This is a bug in the tactic itself. -- Lean's concurrency model is coöperative, which means a tactic is responsible - for checking a cancellation flag if it runs for a long time. Pantograph's - built-in timeout feature requires such behaviour. A tactic which hangs without - checking the flag cannot be timeouted. -- Interceptions of parsing errors generally cannot be turned into goals (e.g. - `def mystery : Nat := :=`) due to Lean's parsing system. - -Each Pantograph version is anchored to a Lean version specified in -`src/lean-toolchain`. Features can be backported to older Lean versions upon -request. - -## Referencing - -[Paper Link](https://arxiv.org/abs/2410.16429) - -```bib -@misc{pantograph, - title={Pantograph: A Machine-to-Machine Interaction Interface for Advanced Theorem Proving, High Level Reasoning, and Data Extraction in Lean 4}, - author={Leni Aniva and Chuyue Sun and Brando Miranda and Clark Barrett and Sanmi Koyejo}, - year={2024}, - eprint={2410.16429}, - archivePrefix={arXiv}, - primaryClass={cs.LO}, - url={https://arxiv.org/abs/2410.16429}, -} -``` diff --git a/apn/lean/pypantograph-docs/setup.md b/apn/lean/pypantograph-docs/setup.md deleted file mode 100644 index fa194fcc..00000000 --- a/apn/lean/pypantograph-docs/setup.md +++ /dev/null @@ -1,85 +0,0 @@ -# Setup - -1. Install `uv` -2. Clone this repository with submodules: -```sh -git clone --recurse-submodules -``` -3. Install `elan` and `lake`: See [Lean Manual](https://docs.lean-lang.org/lean4/doc/setup.html) -4. Execute -```sh -cd -uv sync -``` - -`uv build` builds a wheel of Pantograph in `dist` which can then be installed. For -example, a downstream project could have this line in its `pyproject.toml` - -```toml -pantograph = { file = "path/to/wheel/dist/pantograph-0.3.0-cp312-cp312-manylinux_2_40_x86_64.whl" } -``` - -All interactions with Lean pass through the `Server` class. Create an instance of Pantograph using -```python -from pantograph import Server -server = Server() -``` - -## Lean Dependencies - -The server created from `Server()` is sufficient for basic theorem proving tasks -reliant on Lean's `Init` library. Some users may find this insufficient and want -to use non-builtin libraries such as Aesop or Mathlib4. In this case, feed in a -list of module names via the `imports` parameter e.g. `imports=["Mathlib"]`. Due -to inherent restrictions in Lean, importing a module that has not been imported -before after the server has already started is not allowed and will trigger -initializer exceptions. It may be possible to circumvent this if Lean relaxes -this constraint. - -To use external Lean dependencies such as -[Mathlib4](https://github.com/leanprover-community/mathlib4), Pantograph relies -on an existing Lean repository. Instructions for creating this repository can be -found [here](https://docs.lean-lang.org/lean4/doc/setup.html#lake). - -After creating this initial Lean repository, execute in the repository -```sh -lake build -``` - -to build all files from the repository. This step is necessary after any file in -the repository is modified. - -Then, feed the repository's path to the server -```python -server = Server(project_path="./path-to-lean-repo/") -``` - -For a complete example, see `examples/`. - -## Server Parameters - -The server has some additional options. - -- `core_options`: These options are passed to Lean's kernel. For example - `set_option pp.all true` in Lean corresponds to passing `pp.all=true` to - `core_options`. -- `options`: These options are given to Pantograph itself. See below. -- `timeout`: This timeout controls the maximum wait time for the server - instance. If the server instance does not respond within this timeout limit, - it gets terminated. In some cases it is necessary to increase this if loading - a Lean project takes too long. - -A special note about running in Jupyter: Use the asynchronous version of each -function. - -```python -server = await Server.create() -unit, = await server.load_sorry_async(sketch) -print(unit.goal_state) -``` - -### Options - -- `automaticMode`: Set to false to disable automatic goal continuation. -- `timeout`: Set to a positive integer to set tactic execution timeout. -- `printDependentMVars`: Set to true to explicitly store goal inter-dependencies diff --git a/apn/prompts.py b/apn/prompts.py index 97784718..531ce088 100644 --- a/apn/prompts.py +++ b/apn/prompts.py @@ -31,8 +31,6 @@ def encouragement_prompt() -> str: def user_prompt(path: str, token_limit: int | None, literature: bool, util_module: str) -> str: parts = [] - PYTHON_LIBS = ["sympy", "mpmath", "numpy", "pantograph"] - PROOF_PATH = "/workspace/leanproject/Submission/Spec.lean" parts.append(f"""\ @@ -50,11 +48,13 @@ def user_prompt(path: str, token_limit: int | None, literature: bool, util_modul Your submission may depend only on the following axioms: {', '.join(f'`{a}`' for a in PERMITTED_AXIOMS)}. Don't attempt to cheat with Lean loopholes, the verifier will reject such attempts. Your environment has the following available: -* A Lean 4 toolchain with Mathlib +* A Lean 4 toolchain with Mathlib, plus `loogle` for searching Mathlib by constant name or type pattern (e.g. `loogle 'Nat.Prime, _ ^ _'` or `loogle '|- tsum _ = _ * tsum _'`). To inspect a goal state, insert `trace_state` into a tactic proof and run `lake env lean `: the goal is printed on stdout (an unfinished proof likewise prints its unsolved goals). +* The `sage` computer algebra system (version 10), with `gp` (PARI), `gap`, `Singular`, and `maxima` also on PATH. +* `python3` with numpy, scipy, sympy, mpmath, pandas, networkx, igraph, python-flint (fast arbitrary-precision number theory), highspy (LP/MIP), python bindings for the solvers below (z3, cvc5, OR-Tools CP-SAT, pysat), snappy (SnapPy, 3-manifolds), and ore_algebra (D-finite sequences, used from sage). +* Solver binaries: `z3`, `cvc5`, `kissat` (SAT, DIMACS), `cryptominisat` (SAT), `csdp` (semidefinite programs), `msolve` (polynomial systems), `prover9`/`mace4` (first-order prover / countermodel finder). +* Mathematical CLI tools: `primesieve`, `primecount`, `ecm` (integer factorization), nauty's generators (`geng`, `genbg`, ...), `plantri` (planar graphs), `polymake` (polyhedral geometry), `normaliz` (rational cones), 4ti2 (lattice ideals), `lrs` (vertex enumeration), `M2` (Macaulay2, commutative algebra), `regina-python` (low-dimensional topology). * `git`, `rg`, and `jq` -* The `sage` computer algebra system -* `python` with the following libraries: {', '.join(f'`{lib}`' for lib in PYTHON_LIBS)}. -* Documentation for libraries is available at `/opt/` +* Documentation for the less famous tools is available at `/opt/docs` Blindly searching for counterexamples using numerics is rarely a good approach. """) diff --git a/apn/redteam.py b/apn/redteam.py index cad29dff..1ecdb274 100644 --- a/apn/redteam.py +++ b/apn/redteam.py @@ -110,8 +110,9 @@ def collatzStep (n : ℕ) : ℕ := if n % 2 = 0 then n / 2 else 3 * n + 1 cannot break it, report what you tried and why each approach failed. Be persistent and methodical: when one approach fails, understand why from the -codebase and try another. You have a Lean toolchain, `git`, `rg`, `jq`, `python` -(sympy/mpmath/numpy/pantograph), and `sage` available. +codebase and try another. You have a Lean toolchain, `git`, `rg`, `jq`, `python3` +(numpy/scipy/sympy/mpmath and more), `sage`, and a suite of solver and math CLI +tools available. """ @@ -123,7 +124,7 @@ def _apn_codebase_tar() -> bytes: root = Path(apn.__file__).parent skip_top = {"data", "__pycache__"} - skip_any = {"__pycache__", "pantograph-docs", "pypantograph-docs"} + skip_any = {"__pycache__", "docs"} buf = io.BytesIO() with tarfile.open(fileobj=buf, mode="w:gz") as tf: for p in sorted(root.rglob("*")): diff --git a/pyproject.toml b/pyproject.toml index 10ef6e4d..a7aeae7c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "apn" -version = "0.1.9" +version = "0.1.10rc1" description = "An Inspect implementation of the AlphaProof Nexus formal proof-search framework" license = "MIT AND Apache-2.0" license-files = ["LICENSE"] @@ -48,8 +48,6 @@ files = ["apn", "tests"] # tests/ is a namespace package (no __init__.py); tests import shared plumbing # as `tests.lean_sandbox`, so pin the repo root as the package base. explicit_package_bases = true -# Vendored third-party docs/examples, not our code. -exclude = 'pypantograph-docs' strict = true # Inspect ships py.typed; lean on its annotations. warn_unused_configs = true diff --git a/tests/test_agent_image.py b/tests/test_agent_image.py new file mode 100644 index 00000000..f88436cb --- /dev/null +++ b/tests/test_agent_image.py @@ -0,0 +1,268 @@ +"""Contract test for the agent image's declared compute stack. + +The agent image's tool roster is *declared* -- in ``apn/lean/compute-env.yaml`` +plus the explicit install lines of the Dockerfile's ``compute_build``/ +``solvers_build``/``agent`` stages -- and advertised to the agent by +``apn.prompts.user_prompt``. This suite is the hardcoded contract between the +two: every advertised binary resolves, every advertised python module imports, +a handful of end-to-end smokes prove the big tools actually run (a present +binary with a broken runtime, e.g. a Sage missing its GAP, would pass a bare +``command -v``), and the vendored docs directories exist. If an install line is +dropped or a conda pin stops shipping a binary, this fails before an eval does. + +Every exec runs through ``bash --login -c`` -- exactly how the agent's bash +tool executes (``apn.tools``) -- so the PATH plumbing (/opt/env/bin first, via +/etc/profile.d) is itself under test. + +The agent (``default``) sandbox is brought up **once for the whole module** +through Inspect's lifecycle from the production compose +(``apn.task.get_compose_file``, which builds from ``apn/lean/Dockerfile``), +exactly like ``tests/test_gold_proofs.py``, sharing one module-scoped event +loop. Docker is part of the test environment, so this always runs. +""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from contextlib import asynccontextmanager + +import pytest +import pytest_asyncio +from inspect_ai.util import SandboxEnvironment +from inspect_ai.util._sandbox.context import ( + cleanup_sandbox_environments_sample, + init_sandbox_environments_sample, +) +from inspect_ai.util._sandbox.docker.docker import DockerSandboxEnvironment + +from apn.dataset import OEIS_DIR, fc_commit +from apn.task import get_compose_file + +# --------------------------------------------------------------------------- # +# The contract: hardcoded rosters (no manifest machinery by design -- these # +# lists and the Dockerfile install lines are maintained together by hand). # +# --------------------------------------------------------------------------- # + +# Binaries, by provenance: +BINARIES = [ + # lean layer (base) + loogle_build + "lake", + "lean", + "loogle", + # conda env (/opt/env/bin; spec: compute-env.yaml) + "python3", + "sage", + "gp", + "gap", + "Singular", + "maxima", + "z3", + "primesieve", + "primecount", + "ecm", + "geng", + "genbg", + "normaliz", + "zsolve", + "lrs", + # solvers_build (/usr/local/bin) + "kissat", + "plantri", + "cvc5", + "msolve", + "prover9", + "mace4", + # apt (bookworm) + "polymake", + "M2", + "regina-python", + "cryptominisat", + "csdp", + "jq", + "rg", + "git", +] + +# Python modules importable from the agent's `python3` (the /opt/env python). +PYTHON_MODULES = [ + "numpy", + "scipy", + "sympy", + "mpmath", + "pandas", + "networkx", + "igraph", + "flint", # python-flint + "highspy", + "fpylll", + "z3", + "cvc5", + "ortools", + "pysat", # python-sat + "snappy", # SnapPy + "ore_algebra", + "sage.all", +] + +# Vendored docs directories (apn/lean/docs/ -> /opt/docs/). +DOCS_DIRS = [ + "loogle", + "nauty", + "plantri", + "polymake", + "normaliz", + "4ti2", + "lrslib", + "msolve", + "csdp", + "prover9", + "regina", + "snappy", + "ore_algebra", + "python-flint", +] + + +@asynccontextmanager +async def _sandbox_envs() -> AsyncIterator[dict[str, SandboxEnvironment]]: + """Bring up the production compose and yield the live ``{name: env}`` dict + (mirrors ``tests/test_gold_proofs.py``; the agent workspace is ``default``).""" + compose = str(get_compose_file(fc_commit(OEIS_DIR), literature=False)) + task_name = "pytest_agent_image" + await DockerSandboxEnvironment.task_init(task_name, compose) + try: + envs = await init_sandbox_environments_sample( + sandboxenv_type=DockerSandboxEnvironment, + task_name=task_name, + config=compose, + files={}, + setup=None, + metadata={}, + ) + try: + yield envs + finally: + await cleanup_sandbox_environments_sample( + type="docker", + task_name=task_name, + config=compose, + environments=envs, + interrupted=False, + ) + finally: + await DockerSandboxEnvironment.task_cleanup(task_name, compose, cleanup=True) + + +@pytest_asyncio.fixture(loop_scope="module", scope="module") +async def agent_env() -> AsyncIterator[SandboxEnvironment]: + async with _sandbox_envs() as envs: + yield envs["default"] + + +async def _bash( + env: SandboxEnvironment, command: str, timeout: int = 120 +) -> tuple[int, str, str]: + """Run ``command`` exactly as the agent's bash tool does (login shell).""" + result = await env.exec(["bash", "--login", "-c", command], timeout=timeout) + return result.returncode, result.stdout, result.stderr + + +@pytest.mark.asyncio(loop_scope="module") +@pytest.mark.parametrize("binary", BINARIES) +async def test_binary_on_path(agent_env: SandboxEnvironment, binary: str) -> None: + code, stdout, stderr = await _bash(agent_env, f"command -v {binary}") + assert code == 0, f"binary {binary!r} not on the agent's login-shell PATH" + + +@pytest.mark.asyncio(loop_scope="module") +@pytest.mark.parametrize("module", PYTHON_MODULES) +async def test_python_module_imports( + agent_env: SandboxEnvironment, module: str +) -> None: + # Sage-adjacent imports (sage.all, ore_algebra, snappy) are slow cold. + code, stdout, stderr = await _bash( + agent_env, f"python3 -c 'import {module}'", timeout=300 + ) + assert code == 0, f"import {module} failed:\n{stderr[-2000:]}" + + +@pytest.mark.asyncio(loop_scope="module") +@pytest.mark.parametrize("tool", DOCS_DIRS) +async def test_docs_dir_present(agent_env: SandboxEnvironment, tool: str) -> None: + # Non-empty, not merely present. + code, stdout, _ = await _bash(agent_env, f"ls /opt/docs/{tool} | head -1") + assert code == 0 and stdout.strip(), f"/opt/docs/{tool} missing or empty" + + +# --------------------------------------------------------------------------- # +# End-to-end smokes: the big tools actually run. # +# --------------------------------------------------------------------------- # + + +@pytest.mark.asyncio(loop_scope="module") +async def test_sage_factors(agent_env: SandboxEnvironment) -> None: + code, stdout, stderr = await _bash( + agent_env, "sage -c 'print(factor(2^67-1))'", timeout=600 + ) + assert code == 0, f"sage failed:\n{stderr[-2000:]}" + assert stdout.strip() == "193707721 * 761838257287" + + +@pytest.mark.asyncio(loop_scope="module") +async def test_geng_counts_graphs_on_five_vertices( + agent_env: SandboxEnvironment, +) -> None: + code, stdout, _ = await _bash(agent_env, "geng -q 5 | wc -l") + assert code == 0 + assert stdout.strip() == "34" + + +@pytest.mark.asyncio(loop_scope="module") +async def test_cpsat_solves_trivial_model(agent_env: SandboxEnvironment) -> None: + script = ( + "from ortools.sat.python import cp_model\n" + "m = cp_model.CpModel()\n" + "x = m.new_int_var(0, 10, 'x')\n" + "m.add(x > 7)\n" + "s = cp_model.CpSolver()\n" + "assert s.solve(m) == cp_model.OPTIMAL\n" + "print(s.value(x))\n" + ) + code, stdout, stderr = await _bash( + agent_env, f"python3 - <<'EOF'\n{script}EOF", timeout=300 + ) + assert code == 0, f"CP-SAT smoke failed:\n{stderr[-2000:]}" + + +@pytest.mark.asyncio(loop_scope="module") +async def test_loogle_finds_nat_prime(agent_env: SandboxEnvironment) -> None: + # Cold start loads the prebuilt index + Mathlib oleans; generous timeout. + code, stdout, stderr = await _bash( + agent_env, "loogle 'Nat.Prime'", timeout=900 + ) + assert code == 0, f"loogle failed:\n{stderr[-2000:]}" + assert "Nat.Prime" in stdout + + +@pytest.mark.asyncio(loop_scope="module") +async def test_trace_state_prints_goal(agent_env: SandboxEnvironment) -> None: + """The prompt's advertised goal-state idiom: `trace_state` before a `sorry` + prints the goal on stdout under `lake env lean` (regression-pins the + workflow the agent is told to use, in the real Lake project).""" + lean = ( + "import Mathlib.Tactic\\n" + "example (a b : Nat) : a + b = b + a := by\\n" + " trace_state\\n" + " sorry\\n" + ) + code, stdout, stderr = await _bash( + agent_env, + "cd /workspace/leanproject && mkdir -p Submission " + f"&& printf '{lean}' > Submission/TraceStateSmoke.lean " + "&& lake env lean Submission/TraceStateSmoke.lean; rc=$?; " + "rm -f Submission/TraceStateSmoke.lean; exit $rc", + timeout=600, + ) + # `sorry` warns but exits 0; the goal state must appear on stdout. + assert code == 0, f"lake env lean failed:\n{stderr[-2000:]}\n{stdout[-2000:]}" + assert "a + b = b + a" in stdout, f"goal state not printed:\n{stdout[-2000:]}" diff --git a/tests/test_tools.py b/tests/test_tools.py index 84b76e6f..9e97a1b7 100644 --- a/tests/test_tools.py +++ b/tests/test_tools.py @@ -21,10 +21,21 @@ def test_user_prompt_references_path() -> None: assert PROOF_PATH in rendered -def test_user_prompt_mentions_lean_and_pypantograph() -> None: +def test_user_prompt_mentions_environment_tools() -> None: + # Sentinel tools from each layer of the agent image's compute stack: the + # lean layer (loogle), the conda env (sage, z3), the source-built solvers + # (kissat), the goal-state idiom, and the vendored docs location. rendered = user_prompt(PROOF_PATH, token_limit=None, literature=False, util_module=UTIL_MODULE) assert "Lean 4" in rendered - assert "pantograph" in rendered.lower() + assert "loogle" in rendered + assert "sage" in rendered + assert "z3" in rendered + assert "kissat" in rendered + assert "trace_state" in rendered + assert "/opt/docs" in rendered + # The pantograph toolchain is gone from the image; the prompt must not + # advertise it. + assert "pantograph" not in rendered.lower() # Statement-integrity rule must still be present (it's the one substantive # constraint the agent gets from the prompt rather than from the verifier). assert "statement" in rendered diff --git a/uv.lock b/uv.lock index 8f2c70b4..03288fe9 100644 --- a/uv.lock +++ b/uv.lock @@ -182,7 +182,7 @@ wheels = [ [[package]] name = "apn" -version = "0.1.9" +version = "0.1.10rc1" source = { editable = "." } [package.dev-dependencies] From d3e334c9c94d60cf2b79ccb96120a8e1b45b3b7f Mon Sep 17 00:00:00 2001 From: tadamcz Date: Fri, 28 Aug 2026 23:03:08 +0100 Subject: [PATCH 2/7] Verify the agent compute stack; vendor tool docs; finalize Loogle The full agent image now builds at the oeis pin and passes the new contract suite end to end (binaries, imports, sage/geng/CP-SAT/loogle smokes, docs dirs). Fixes found by building: prover9 fetched as a tarball (no git in solvers_build), msolve's binary lands at the build root, ore_algebra installed pure-python (Cython >= 3.2, required env-wide by sage 10.9, cannot compile its optional arb extensions) and imported after sage.all, libmpfr6 declared for msolve. Loogle, per the build spike: the binary is statically linked, ignores LEAN_PATH, and takes --path flags that replace its whole search path, so a wrapper (loogle.sh) passes the FC project's package roots plus the toolchain stdlib; the index is prebuilt in loogle_build where the Mathlib rev provably matches. /opt/loogle ships binary + own oleans + index (~560 MB) with no second Mathlib copy. Vendored docs: apn/lean/docs/ -> /opt/docs/, 14 tools, ~1 MB total, text/markdown only, one provenance line each, upstream LICENSE per dir, version-matched to the installed packages. --- apn/lean/Dockerfile | 72 +- apn/lean/docs/4ti2/4ti2-manual.txt | 1568 +++++++++ apn/lean/docs/4ti2/LICENSE | 339 ++ apn/lean/docs/csdp/LICENSE | 237 ++ apn/lean/docs/csdp/csdp-user-guide.txt | 335 ++ apn/lean/docs/loogle/LICENSE | 71 + apn/lean/docs/loogle/loogle.md | 71 + apn/lean/docs/lrslib/LICENSE | 339 ++ apn/lean/docs/lrslib/lrs-userguide.md | 1065 ++++++ apn/lean/docs/msolve/LICENSE | 339 ++ apn/lean/docs/msolve/msolve-tutorial.txt | 742 ++++ apn/lean/docs/nauty/COPYRIGHT | 44 + apn/lean/docs/nauty/LICENSE | 202 ++ apn/lean/docs/nauty/nauty-guide.txt | 2039 +++++++++++ apn/lean/docs/normaliz/LICENSE | 682 ++++ apn/lean/docs/normaliz/normaliz-manual.txt | 3604 ++++++++++++++++++++ apn/lean/docs/ore_algebra/LICENSE | 339 ++ apn/lean/docs/ore_algebra/ore_algebra.md | 1709 ++++++++++ apn/lean/docs/plantri/LICENSE | 202 ++ apn/lean/docs/plantri/plantri-guide.txt | 1579 +++++++++ apn/lean/docs/polymake/LICENSE | 361 ++ apn/lean/docs/polymake/polymake.md | 1872 ++++++++++ apn/lean/docs/prover9/LICENSE | 339 ++ apn/lean/docs/prover9/prover9-manual.md | 3218 +++++++++++++++++ apn/lean/docs/python-flint/LICENSE | 22 + apn/lean/docs/python-flint/python-flint.md | 375 ++ apn/lean/docs/regina/LICENSE | 470 +++ apn/lean/docs/regina/regina-python.md | 948 +++++ apn/lean/docs/snappy/LICENSE | 351 ++ apn/lean/docs/snappy/snappy.md | 1238 +++++++ apn/lean/loogle.sh | 19 + apn/prompts.py | 4 +- tests/test_agent_image.py | 5 +- tests/test_tools.py | 1 - 34 files changed, 24770 insertions(+), 31 deletions(-) create mode 100644 apn/lean/docs/4ti2/4ti2-manual.txt create mode 100644 apn/lean/docs/4ti2/LICENSE create mode 100644 apn/lean/docs/csdp/LICENSE create mode 100644 apn/lean/docs/csdp/csdp-user-guide.txt create mode 100644 apn/lean/docs/loogle/LICENSE create mode 100644 apn/lean/docs/loogle/loogle.md create mode 100644 apn/lean/docs/lrslib/LICENSE create mode 100644 apn/lean/docs/lrslib/lrs-userguide.md create mode 100644 apn/lean/docs/msolve/LICENSE create mode 100644 apn/lean/docs/msolve/msolve-tutorial.txt create mode 100644 apn/lean/docs/nauty/COPYRIGHT create mode 100644 apn/lean/docs/nauty/LICENSE create mode 100644 apn/lean/docs/nauty/nauty-guide.txt create mode 100644 apn/lean/docs/normaliz/LICENSE create mode 100644 apn/lean/docs/normaliz/normaliz-manual.txt create mode 100644 apn/lean/docs/ore_algebra/LICENSE create mode 100644 apn/lean/docs/ore_algebra/ore_algebra.md create mode 100644 apn/lean/docs/plantri/LICENSE create mode 100644 apn/lean/docs/plantri/plantri-guide.txt create mode 100644 apn/lean/docs/polymake/LICENSE create mode 100644 apn/lean/docs/polymake/polymake.md create mode 100644 apn/lean/docs/prover9/LICENSE create mode 100644 apn/lean/docs/prover9/prover9-manual.md create mode 100644 apn/lean/docs/python-flint/LICENSE create mode 100644 apn/lean/docs/python-flint/python-flint.md create mode 100644 apn/lean/docs/regina/LICENSE create mode 100644 apn/lean/docs/regina/regina-python.md create mode 100644 apn/lean/docs/snappy/LICENSE create mode 100644 apn/lean/docs/snappy/snappy.md create mode 100644 apn/lean/loogle.sh diff --git a/apn/lean/Dockerfile b/apn/lean/Dockerfile index 93f87077..2eb2a827 100644 --- a/apn/lean/Dockerfile +++ b/apn/lean/Dockerfile @@ -265,16 +265,25 @@ RUN micromamba create -y -p /opt/env -f /tmp/compute-env.yaml \ # topology), not the compression lib. ore_algebra (D-finite guessing over # Sage) has no PyPI release, so it is pinned by commit; its setup.py imports # sage.env, so it must build WITHOUT pip's build isolation, against the env's -# own sage/cython/flint (hence --no-build-isolation and the env's setuptools). +# own sage/cython (hence --no-build-isolation and the env's setuptools). Its +# optional compiled arb extensions do not build under Cython >= 3.2 (which +# sage 10.9 requires env-wide), so the setup is patched onto its own +# no-extensions branch -- the pure-python install it already uses for older +# sage; the guessing/annihilator API is pure python, only numerical +# evaluation loses its fast path. ARG ORE_ALGEBRA_COMMIT=18680180c884fac869a064db99f29a221aad9dfe RUN /opt/env/bin/pip install --no-cache-dir \ python-sat==1.9.dev15 \ cvc5==1.3.4 \ ortools==9.15.6755 \ snappy==3.3.2 \ - && PKG_CONFIG_PATH=/opt/env/lib/pkgconfig \ - /opt/env/bin/pip install --no-cache-dir --no-build-isolation \ - "ore_algebra @ git+https://github.com/mkauers/ore_algebra@${ORE_ALGEBRA_COMMIT}" \ + && curl -sSfL "https://github.com/mkauers/ore_algebra/archive/${ORE_ALGEBRA_COMMIT}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/ore_algebra-* \ + && sed -i "s|^if list(map(int, sage.version.version.split('.')\\[:2\\])) < \\[10, 2\\]:|if True: # patched: pure-python install, Cython >= 3.2 cannot build the arb extensions|" setup.py \ + && grep -q '^if True:' setup.py \ + && /opt/env/bin/pip install --no-cache-dir --no-build-isolation . \ + && cd / && rm -rf /tmp/ore_algebra-* \ && find /opt/env -name '__pycache__' -type d -prune -exec rm -rf {} + # --------------------------------------------------------------------------- # @@ -366,26 +375,44 @@ RUN arch="$(uname -m)" \ # --------------------------------------------------------------------------- # FROM base AS loogle_build +# Retarget: the project's toolchain file replaces loogle's (v4.27.0-rc1 -> +# v4.27.0; verified friction-free), and its mathlib require moves from +# "master" to the rev the baked manifest pins. `lake update` then resolves +# the transitive deps to exactly the FC manifest's revs and mathlib's +# post-update hook fetches the olean cache (zero misses at the pinned rev). ARG LOOGLE_COMMIT=79343e3e37b64046e6b555936682012e80300df1 RUN git clone https://github.com/nomeata/loogle.git /opt/loogle-src \ && git -C /opt/loogle-src checkout --detach "${LOOGLE_COMMIT}" \ && cd /opt/loogle-src \ && cp /workspace/leanproject/lean-toolchain lean-toolchain \ && MATHLIB_REV="$(python3 -c "import json; print(next(p['rev'] for p in json.load(open('/workspace/leanproject/lake-manifest.json'))['packages'] if p['name'] == 'mathlib'))")" \ - && sed -i "s|require mathlib from git \"https://github.com/leanprover-community/mathlib4\" @ \"master\"|require mathlib from git \"https://github.com/leanprover-community/mathlib4\" @ \"${MATHLIB_REV}\"|" lakefile.lean \ + && sed -i "s|@ \"master\"|@ \"${MATHLIB_REV}\"|" lakefile.lean \ && grep -q "@ \"${MATHLIB_REV}\"" lakefile.lean \ && rm lake-manifest.json \ && lake update \ - && lake exe cache get \ && lake build loogle -# Stage the runtime pieces: the binary plus loogle's own module oleans (its -# Mathlib/dependency oleans are NOT staged -- the agent image points LEAN_PATH -# at the FC project's baked packages, same toolchain and Mathlib rev by -# construction). -RUN mkdir -p /opt/loogle/bin \ +# Stage the runtime pieces -- the binary (statically linked against the +# toolchain: no lake env / LD_LIBRARY_PATH needed), loogle's own module +# oleans, and the prebuilt search index (built here, where a Mathlib rev +# identical to the runtime one is guaranteed; peaks ~10 GB RSS). Its +# Mathlib/dependency oleans are NOT staged: at runtime the wrapper passes +# --path flags for the FC project's baked packages, same toolchain and +# Mathlib rev by construction. The --json query doubles as a smoke test. +RUN mkdir -p /opt/loogle/bin /opt/loogle/lib \ && cp /opt/loogle-src/.lake/build/bin/loogle /opt/loogle/bin/loogle \ - && cp -r /opt/loogle-src/.lake/build/lib/lean /opt/loogle/lib + && cp -r /opt/loogle-src/.lake/build/lib/lean /opt/loogle/lib/lean \ + && find /opt/loogle/lib -type f ! -name '*.olean' -delete \ + && /opt/loogle/bin/loogle \ + $(for p in /workspace/leanproject/.lake/packages/*/.lake/build/lib/lean; do printf ' --path %s' "$p"; done) \ + --path /workspace/leanproject/.lake/build/lib/lean \ + --path /opt/loogle/lib/lean \ + --path "/root/.elan/toolchains/$(sed 's|/|--|g; s|:|---|g' /workspace/leanproject/lean-toolchain)/lib/lean" \ + --write-index /opt/loogle/loogle.index --json "Nat.Prime" \ + > /tmp/loogle-smoke.json \ + && grep -q '"name"' /tmp/loogle-smoke.json \ + && rm /tmp/loogle-smoke.json \ + && rm -rf /opt/loogle-src # --------------------------------------------------------------------------- # # agent: the agent's workspace. Layer order is big/stable first (the conda # @@ -416,22 +443,13 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # Source-built solvers (kissat, plantri, prover9/mace4, msolve, cvc5). COPY --from=solvers_build /out/bin/ /usr/local/bin/ -# Loogle: binary + its own module oleans; Mathlib resolves from the FC -# project's baked packages via LEAN_PATH (same toolchain + Mathlib rev as the -# loogle_build stage by construction). The wrapper makes `loogle "..."` work -# without the agent knowing any of this. +# Loogle: binary + its own module oleans + prebuilt index; Mathlib resolves +# from the FC project's baked packages (same toolchain + Mathlib rev as the +# loogle_build stage by construction). The wrapper passes the --path roster +# so `loogle "..."` works without the agent knowing any of this. COPY --from=loogle_build /opt/loogle /opt/loogle -RUN printf '%s\n' \ - '#!/bin/sh' \ - '# Loogle needs its own oleans plus the project Mathlib oleans on LEAN_PATH.' \ - 'LEAN_PATH=/opt/loogle/lib' \ - 'for d in /workspace/leanproject/.lake/packages/*/.lake/build/lib/lean; do' \ - ' LEAN_PATH="$LEAN_PATH:$d"' \ - 'done' \ - 'export LEAN_PATH' \ - 'exec /opt/loogle/bin/loogle "$@"' \ - > /usr/local/bin/loogle \ - && chmod 755 /usr/local/bin/loogle +COPY loogle.sh /usr/local/bin/loogle +RUN chmod 755 /usr/local/bin/loogle # In-sandbox references (the sandbox has no network): vendored, version-matched # docs for the tools whose syntax the agent is unlikely to know cold. Last: diff --git a/apn/lean/docs/4ti2/4ti2-manual.txt b/apn/lean/docs/4ti2/4ti2-manual.txt new file mode 100644 index 00000000..111546e0 --- /dev/null +++ b/apn/lean/docs/4ti2/4ti2-manual.txt @@ -0,0 +1,1568 @@ + + + +Chapter 1 + +Beginner’s guide + +In this part, we use a few sample problems to introduce you to the basic functionality +of 4ti2. After working through this part, you should know about linear systems and +their encodings in 4ti2, and should be able to do computations using the following +functions: + + • qsolve, rays, circuits + + • zsolve, hilbert, graver, ppi + + • minimize, groebner, normalform + + • genmodel, markov + + + +1.1 Linear systems and their encodings + +In this section you learn about the data structure linear system and how it is +specified in 4ti2. + + +1.1.1 Linear systems and integer linear systems + +In 4ti2, a linear system is defined by d constraints Ax ∼ b in n unknowns x, where +each constraint is either ≤, = or ≥, that is ∼ ∈ {≤, =, ≥}d . Moreover, one may + + 5 +1.1. Linear systems and their encodings 6 + + +specify sign constraints on the variables that need to be respected in an explicit +continuous/integer representation of all solutions. +There is no particular difference in 4ti2 between a linear system and an integer +linear system. Currently, the user chooses between one of the two by calling the +appropriate functions on the linear system. + + +1.1.2 Specifying a linear system in 4ti2 + +In order to use a linear system as input, we need to specify its parts to 4ti2. As our +running example, take + ! ! + 1 1 1 1 ≤ 6 + x + 1 2 3 4 ≤ 10 + +with sign constraints (1, 2, 2, 0), which we will explain below. +First, we have to give our problem a project name, say PROJECT. + + • The matrix A has to be put into the file PROJECT.mat. + + 2 4 + 1 1 1 1 + 1 2 3 4 + + • The relations ∼ then have to be specified in PROJECT.rel. + + 1 2 + < < + + • The right-hand side vector goes into PROJECT.rhs. + + 1 2 + 6 10 + + • And finally, the sign constraints end up in PROJECT.sign. + + 1 4 + 1 2 2 0 +Chapter 1. Beginner’s guide 7 + + +Note. + + • The input files all have the format of a matrix, preceded by the matrix di- + mensions. As the dimensions already specify how many symbols have to be + read, the matrix could also be given in only one line or even in many lines of + different lengths. + + • In 4ti2 version 1.3.1 and later, all appearing numbers have to be integers. + + • Consequently, this implies that, at the moment, qsolve only supports homoge- + neous linear systems, that is systems with b = 0, since minimal inhomogeneous + solutions could have rational components. + + +1.1.3 What does an explicit solution to linear systems look + like? + +If the system is solved over R (using qsolve), 4ti2 returns two sets of integer +vectors: + + • a set H of support-minimal homogeneous solutions, and + + • a set F defining the linear vector space the solution set lives in. + +As only homogeneous linear systems are supported in this version of 4ti2, no list of +minimal inhomogeneous solutions is computed. Any solution z of the linear system +can now be written as + X X + z= αj hj + βk fk (1.1) + +with hj ∈ H, fk ∈ F , and αj ≥ 0. +If the system is solved over Z (using zsolve), 4ti2 returns three sets of integer +vectors: + + • a set H of minimal homogeneous integer solutions, + + • a set I of minimal inhomogeneous integer solutions, and + + • a set F defining the sublattice of Zn the solution set lives in. +1.2. Brief tutorial 8 + + +Any solution z of the linear system can now be written as + X X + z =i+ αj hj + βk f k (1.2) + +for some i ∈ I and with hj ∈ H, fj ∈ F , and αj ∈ Z+ . + +Sign file. Let us finally clarify what the sign file PROJECT.sign is good for. The +sign file may declare a variable to be non-negative (1), to be non-positive (−1), or +to consider both cases independently and unite the answers (2). If a nonzero sign +has been assigned to a variable, the explicit representations (1.1) and (1.2) above +of a solution z have to respect the sign on that variable. The default setting for +each variable is 0 (when using qsolve and zsolve), that is, the sign need not be +respected in the explicit representation. In our example above, the first variable +is declared to be non-negative, the second and the third one expand to 2 · 2 = 4 +orthant constraints, and the fourth variable is unconstrained. Note, however, that +4ti2 does not decompose the problem internally into the four problems with sign +patterns (1, 1, 1, 0), (1, 1, −1, 0), (1, −1, 1, 0), and (1, −1, −1, 0), but deals with them +more efficiently at the same time. + + + + +1.2 Brief tutorial + +1.2.1 Solving linear systems over Z with zsolve + +In this example you learn about the function zsolve. + +Let us have a look at the linear system + + + x − y ≤ 2 + −3x + y ≤ 1 + x + y ≥ 1 + y ≥ 0 + +over Z. We have to create the files encoding the linear system. Let us call our project +system. Then the input files look as follows: +Chapter 1. Beginner’s guide 9 + + + system.mat system.rel system.rhs system.sign + 3 2 1 3 1 3 1 2 + 1 −1 < < > 2 1 1 0 1 + −3 1 + 1 1 +Then we call + + ./zsolve system + +This call creates two files + system.zinhom system.zhom + 4 2 3 2 + 0 1 1 1 + 2 0 1 2 + 1 0 1 3 + 1 1 +which correspond to the explicit description of all integer solutions: + Feasible solutions Computed representation + y = 3x + 1 y = 3x + 1 + 0000000000000 + 1111111111111 + 0000000000000 + 1111111111111 + 1111111111111 + 0000000000000 + 1111111111111 + 0000000000000 + 0000000000000 + 1111111111111 + 7 111111111111111111111111111 + 111111111111111111111111111 + 000000000000000000000000000 7 1111111111111 + 0000000000000 + 1111111111111 + 0000000000000 + 000000000000000000000000000 + 111111111111111111111111111 1111111111111 + 0000000000000 + 0000000000000 + 1111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 0000000000000 + 1111111111111 + 1111111111111 + 0000000000000 + 111111111111111111111111111 + 000000000000000000000000000 1111111111111 + 0000000000000 + 0000000000000 + 1111111111111 + 111111111111111111111111111 + 000000000000000000000000000 0000000000000 + 1111111111111 + 111111111111111111111111111 + 000000000000000000000000000 1111111111111 + 0000000000000 + 0000000000000 + 1111111111111 + 6 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 6 1111111111111 + 0000000000000 + 1111111111111 + 0000000000000 + 111111111111111111111111111 + 000000000000000000000000000 0000000000000 + 1111111111111 + 111111111111111111111111111 + 000000000000000000000000000 0000000000000 + 1111111111111 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 5 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 5 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 4 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + y=x-2 4 y=x-2 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 3 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 3 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 2 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 2 + 000000000000000000000000000 + 111111111111111111111111111 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 1 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 1 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 111111111111111111111111111 + 000000000000000000000000000 + 111111111111111111111111111 + 000000000000000000000000000 + 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 + + + +               + 1 2 0 1 1 1 1 + , , , + monoid , , . + 0 0 1 1 1 2 3 +Note that in the pictures above, we are only interested in the lattice points inside +the colored regions! The full regions are colored only for the purpose of visualizing +the covering of all feasible integer solutions by finitely many shifted copies of the +monoid       + 1 1 1 + monoid , , . + 1 2 3 +1.2. Brief tutorial 10 + + +1.2.2 Solving linear systems over Q with qsolve + +qsolve solves linear systems over Q; however, note that it only supports homoge- +neous linear systems, that is, systems with b = 0. + + + ./qsolve system + + +This call creates files + + system.qhom system.qfree + +To solve an inhomogeneous system Ax = b, x ≥ 0, you (still) need to do some work +yourself: + + + 1. Solve system Ax − bu = 0, x ≥ 0, u ≥ 0 using qsolve. + + 2. Keep those solutions with u = 0. (These generate the recession cone (of un- + bounded directions). + + 3. Normalize those solutions with u > 0 to have u = 1 (by dividing the vector + by u). Be aware that this could create rational numbers. + + 4. Drop the u-component. + + +Any solution to Ax = b, x ≥ 0 can then be obtained by adding one solution from 3. +to a nonnegative linear combination of solutions from 2. + + +1.2.3 Computing extreme rays and Hilbert bases + +In this example you learn about the functions rays and hilbert. (They are conve- +nient versions of qsolve and zsolve for particular cases.) +Let us consider the set of magic 3 × 3 squares with non-negative real entries, that +is, the set of all 3 × 3 arrays with non-negative real entries whose row sums, column +sums, and main diagonal sums all add up to the same number, the magic constant +of the square. +Chapter 1. Beginner’s guide 11 + + + + +Clearly, addition of two magic squares gives another magic square, as well as does +multiplication of a magic square by a non-negative number. Therefore, we may talk +about the cone of magic 3 × 3 squares. In fact, this cone is a pointed rational +polyhedral cone described by the linear system + + x11 + x12 + x13 = x21 + x22 + x23 + = x31 + x32 + x33 + = x11 + x21 + x31 + = x12 + x22 + x32 + = x13 + x23 + x33 + = x11 + x22 + x33 + = x31 + x22 + x13 + xij ≥ 0, for all i, j = 1, 2, 3. + +Bringing all xij to the left-hand side of these equations, the matrix A3×3 defining +this linear system is +   + 1 1 1 −1 −1 −1 0 0 0 + 0 −1 −1 −1  +   +  1 1 1 0 0 +   +  0 1 1 −1 0 0 −1 0 0  +   + A3×3 =  1 0 1 0 −1 0 0 −1 0 . +   +   +  1 1 0 +  0 0 −1 0 0 −1   +  0 1 1 +  0 −1 0 0 0 −1   + 1 1 0 0 −1 0 −1 0 0 + +Below, we will deal with the more interesting case of integer magic squares. For the +moment, however, we wish to compute the extreme rays of the magic square cone +{z : A3×3 z = 0, z ≥ 0}. +In order to call the function rays, we only have to create one file, say magic3x3.mat, +in which we specify the problem matrix A3×3 . The remaining data is set by default to +1.2. Brief tutorial 12 + + +”equations only”, to ”homogeneous system”, and to ”all variables are non-negative”. +Note that we are allowed to change these defaults (except homogeneity) by specifying +data in magic3x3.rel and magic3x3.sign + + magic3x3.mat + 7 9 + 1 1 1 −1 −1 −1 0 0 0 + 1 1 1 0 0 0 −1 −1 −1 + 0 1 1 −1 0 0 −1 0 0 + 1 0 1 0 −1 0 0 −1 0 + 1 1 0 0 0 −1 0 0 −1 + 0 1 1 0 −1 0 0 0 −1 + 1 1 0 0 −1 0 −1 0 0 + +Now we call + + ./rays magic3x3 + +which creates the single file + + magic3x3.ray + 4 9 + 0 2 1 2 1 0 1 0 2 + 1 2 0 0 1 2 2 0 1 + 2 0 1 0 1 2 1 2 0 + 1 0 2 2 1 0 0 2 1 + +that corresponds to the four extremal rays of the 3 × 3 magic square cone: + 0 2 1 1 2 0 2 0 1 1 0 2 + 2 1 0 0 1 2 0 1 2 2 1 0 + 1 0 2 2 0 1 1 2 0 0 2 1 + +Every magic 3 × 3 square is a non-negative linear combination of these four magic +squares. +If we turn now to integer magic squares, we are looking for a Hilbert basis of the +3 × 3 magic square cone. As the default settings for hilbert are the same as for +rays, we can use the same input file +Chapter 1. Beginner’s guide 13 + + + magic3x3.mat + 7 9 + 1 1 1 −1 −1 −1 0 0 0 + 1 1 1 0 0 0 −1 −1 −1 + 0 1 1 −1 0 0 −1 0 0 + 1 0 1 0 −1 0 0 −1 0 + 1 1 0 0 0 −1 0 0 −1 + 0 1 1 0 −1 0 0 0 −1 + 1 1 0 0 −1 0 −1 0 0 + +for this computation. However, to compute the Hilbert basis, we call + + ./hilbert magic3x3 + +which creates the single output file + + magic3x3.hil + 5 9 + 0 2 1 2 1 0 1 0 2 + 1 2 0 0 1 2 2 0 1 + 2 0 1 0 1 2 1 2 0 + 1 0 2 2 1 0 0 2 1 + 1 1 1 1 1 1 1 1 1 + +that corresponds to the five elements in the minimal Hilbert basis of the 3 × 3 magic +square cone: + + 0 2 1 1 2 0 2 0 1 1 0 2 + 2 1 0 0 1 2 0 1 2 2 1 0 + 1 0 2 2 0 1 1 2 0 0 2 1 + + + 1 1 1 + 1 1 1 + 1 1 1 +1.2. Brief tutorial 14 + + +Every integer magic 3 × 3 square is a non-negative integer linear combination of +these five integer magic squares. Note that the all-1 square is in the interior of the +magic square cone. +See [2, section 3.8] or [6] for details on the algorithm implemented. + + +1.2.4 Computing circuits and Graver bases + +In this example you learn about the functions graver, ppi, and circuits. +As an example of a Graver basis computation, let us compute the primitive partition +identities of order n = 4. Before we do the simple computation, let us explain what +a primitive partition identity is. +A partition identity is any identity of the form + + a1 + . . . + ak = b1 + . . . + bl + +with (generally not distinct) integer numbers 0 < ai , bj ≤ n. A partition identity is +called primitive if no proper subidentity exists. +For example, + 1+2+3=2+2+2 +is a partition identity which is not primitive, since it contains the subidentity + + 1+3=2+2 + +which is in fact primitive. +The description of the primitive partition identities for fixed n, however, is exactly +the description of the Graver basis of the matrix +   + An = 1 2 3 . . . n . + +Let us finally do the computation for n = 3. We create an input file ppi3 for 4ti2 +which looks as follows: + + ppi3.mat + 1 3 + 1 2 3 +Chapter 1. Beginner’s guide 15 + + +and call + + ./graver ppi3 + +This call will create an output file ppi3.gra that looks like: + + ppi3.gra + 5 3 + 3 0 −1 + 2 −1 0 + 0 3 −2 + 1 1 −1 + 1 −2 1 + +Thus, there are 5 primitive partition identities of order n = 3: + + 1+1+1 = 3 + 1+1 = 2 + 2+2+2 = 3+3 + 1+2 = 3 + 1+3 = 2+2 + +You may try and compute the primitive partition identities for bigger n, say n = 17, +20, or 23. Be aware, especially the latter two problems take a long, long time. What +is the biggest n for which you can compute the primitive partition identities of order +n on your machine within one hour? +Due to the very special structure of the matrix, there are algorithmic speed-ups +[4, 10, 13]. The currently fastest algorithm to compute primitive partition identities +is implemented in the function ppi of 4ti2. Try running + + ./ppi 17 + +which creates two files ppi17.mat (so we do not really have to create this file our- +selves) and the file ppi17.gra containing the desired identities. Compare this run- +ning time with the time taken by +1.2. Brief tutorial 16 + + + ./graver ppi17 + +Do you notice the speed-up? +Let us now turn to the question of determining the support-minimal partition iden- +tities. This, in fact, is the question of computing the circuits of the matrix +   + An = 1 2 3 . . . n . + +We use the same input file + + ppi3.mat + 1 3 + 1 2 3 + +as above and call + + ./circuits ppi3 + +This call will create an output file ppi3.cir that looks like: + + ppi3.cir + 3 3 + 3 0 −1 + 2 −1 0 + 0 3 −2 + +Thus, there are 3 support-minimal partition identities of order n = 3: + + 1+1+1 = 3 + 1+1 = 2 + 2+2+2 = 3+3 + + + +Note that support-minimal partition identities are primitive, since the circuits of a +matrix are contained in the Graver basis of this matrix. +See the book [2, section 3.8], or Hemmecke [7] for details on the algorithm imple- +mented. +Chapter 1. Beginner’s guide 17 + + +1.2.5 Integer programming and toric Gröbner bases + +In this example you learn about the functions minimize, groebner, and normalform. +The following neat example is based on the example presented in [12]. Let us assume +that we want to give change worth 99 cents using only pennies (1ct), nickels (5ct), +dimes (10ct), and quarters (25ct). Clearly, + + 4 · 1 + 4 · 5 + 0 · 10 + 3 · 25 = 99 + +would be one way to do it. Is this there another choice of 11 coins that sums up to +99ct but uses fewer nickels and quarters (in total)? In other words, we would like to +solve + +min{x2 + x4 : x1 + x2 + x3 + x4 = 11, x1 + 5x2 + 10x3 + 25x4 = 99, x1 , x2 , x3 , x4 ∈ Z+ } + +Let us set up the problem in 4ti2. + + 4coins.mat 4coins.zsol 4coins.sign 4coins.cost + 2 4 1 4 1 4 1 4 + 1 1 1 1 4 4 0 3 1 1 1 1 0 1 0 1 + 1 5 10 25 + +Note that we do not have to specify a relations file 4coins.rel, since already by +default all relations are assumed to be equations. Now we simply call + + ./minimize 4coins + +which creates the single output file + + 4coins.min + 1 4 + 4 1 4 2 + +From this, we conclude that + + 4 · 1 + 1 · 5 + 4 · 10 + 2 · 25 = 99 + +is an optimal choice, using only 3 instead of 7 nickels and quarters. +1.2. Brief tutorial 18 + + +Remark. Earlier versions of 4ti2 allowed to specify the right-hand side vector in +a file called 4coins.rhs, instead of giving a solution in 4coins.zsol. This is no +longer supported.  + +Since we already know a feasible solution, there is another way we might attack this +problem, namely via toric Gröbner bases. (See [2, Chapter 11] for an introduction to +toric ideals and their Gröbner bases, and also their generalizations, lattice ideals.) +For this, we first need to specify the matrix A and the cost vector c in the two files +4coins.mat and 4coins.cost: + + 4coins.mat 4coins.cost + 2 4 1 4 + 1 1 1 1 0 1 0 1 + 1 5 10 25 + +Then we compute the Gröbner basis of the toric ideal + + IA = hxu − xv : Au = Av, u, v ∈ Z4+ i + +with respect to a term ordering ≺ compatible with c, that is, c| v < c| u implies +xv ≺ xu . This toric Gröbner basis is computed by + + ./groebner 4coins + +and gives the output file + + 4coins.gro + +Remark. Many algorithm options are available and can be selected by command- +line options of groebner, see section 3.5. As reference to the algorithms we recom- +mend the book [2, section 11.4] or Hemmecke and Malkin [8], as well as Bigatti, +LaScala, and Robbiano [1], Gebauer and Möller [3], and Hoşten and Sturmfels [9]. +Since runnning times of the various algorithms are hard to predict, it may for some +hard problems make sense to start several computations in parallel, each with dif- +ferent algorithms.  + + +Then we specify our feasible solution in +Chapter 1. Beginner’s guide 19 + + + 4coins.feas + 1 4 + 4 4 0 3 + +and call + + ./normalform 4coins + +to produce the file + + 4coins.nf + 1 4 + 4 1 4 2 + +that also contains the desired optimal solution. +Remark. We could also specify a list of feasible solutions in 4coins.feas. Then +the call + + ./normalform 4coins + +creates a file 4coins.nf containing the minima to the corresponding integer pro- +grams. (If z0 is a feasible solution, the corresponding integer program is defined by +putting the right-hand side to Az0 .)  + + + +1.2.6 Markov Bases in Statistics + +In this example you learn about the functions markov and genmodel. +Let us consider the following 4 × 4 table of non-negative integer numbers together +with all row and column sums. +   + 11 23 34 3 71 +  4 15 12 11  42 +   +   +  17 2 3 25  47 + 16 12 22 7 57 + 48 52 71 46 +1.2. Brief tutorial 20 + + +In statistics, one wishes to sample among arrays that have fixed counts, say fixed row +and column sums. In order to sample, one needs a set of moves that, in particular, +do not change the counts when added to the current table. Clearly, these moves +must have counts 0 and thus quite naturally lead us to the toric ideal + + IA = hxu − xv : Au = Av, u, v ∈ Z16 + + i, + +where   + 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 +  0 0 0 0 1 1 1 1 0 0 0 0 0 0 0 0  +   +   +  0 0 0 0 0 0 0 0 1 1 1 1 0 0 0 0  +   +  0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1  + A= . +   +  1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0  +   +  0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0  +   +  0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0  +   + + 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 +It turns out that for any set of fixed counts, a (minimal) Markov basis is given by +a minimal generating set of this toric ideal. Note that a Markov basis connects all +non-negative tables with these counts in the sense that for any two non-negative +tables T1 and T2 with these counts, there is a sequence of non-negative tables T1 = +S0 , . . . , SN = T2 with the same counts as T1 and T2 and such that Si − Si−1 or +Si−1 − Si is in the Markov basis for i = 1, . . . , N . +For two-way tables the situation is still very simple as our computations with 4 × 4 +tables will now demonstrate. Write the matrix that defines our toric ideal in the file +4x4.mat: + + 4x4.mat + 8 16 + 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 + 0 0 0 0 1 1 1 1 0 0 0 0 0 0 0 0 + 0 0 0 0 0 0 0 0 1 1 1 1 0 0 0 0 + 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 + 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 + 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 + 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 + 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 +Chapter 1. Beginner’s guide 21 + + +Let us compute the Markov basis via the call + + ./markov 4x4 + +which creates a single output file 4x4.mar containing the 36 Markov basis elements. +Up to symmetry (swapping rows or columns), the Markov basis consists of the single +move   + 1 −1 0 0 +  −1 1 0 0  + . +   +  +  0 0 0 0  + 0 0 0 0 +In fact, this elementary move is (up to symmetry) the only representative of the +minimal Markov moves for arbitrary m × n tables using row and column counts. +Creating the matrices for statistical models may be pretty cumbersome. 4ti2 pro- +vides a litte function, genmodel, that helps the user with creating matrices for +hierarchical models defined by a complex. +The m × n tables problem above corresponds to the complex {{1}, {2}} on two +nodes with levels m and n, respectively. Let us encode the complex for 3 × 6 tables +with 1-marginals (row and column sums) in 3x6.mod. + + 3x6.mod + 3 + 3 6 + 2 + 1 1 + 1 2 + +and call + + ./genmodel 3x6 + +to produce the desired matrix file 3x6.mat. +The encoding of the complex should be obvious from the example: first we state the +number of nodes and their levels, then we give the number of maximal faces. Finally, +1.2. Brief tutorial 22 + + +we list each maximal face by first specifying the number of nodes on it and then by +listing these nodes. +Thus, a 3 × 4 × 6 table with 2-marginals (that is, again only counts along coordinate +axes) corresponds to the complex {{(1, 2)}, {(2, 3)}, {(3, 1)}} on 3 nodes with levels +3, 4, and 6, respectively. Thus, its encoding is in 4ti2 would look like: + + 3x4x6.mod + 3 + 3 4 6 + 3 + 2 1 2 + 2 2 3 + 2 3 1 + +A binary model on the bipartite graph K2,3 then reads as + + k2 3.mod + 5 + 2 2 2 2 2 + 6 + 2 1 3 + 2 1 4 + 2 1 5 + 2 2 3 + 2 2 4 + 2 2 5 +Chapter 2 + +Advanced guide + +In this part, we deal with several more advanced problem specifications in 4ti2. +First we introduce affine systems and their encodings. In fact, affine systems are +the basic objects used in 4ti2, since every linear system is transformed into an +affine system. However, in the integer situation, it is not always possible to trans- +form an affine system back into a linear system without adding variables or modulo +constraints. + + + +2.1 Affine systems and their encodings + +Let a + LZ be an “integer linear affine space” given by the vector a ∈ Zn and +by generators for the lattice LZ ⊆ Zn . We wish to find a finite sign-compatible +description for the set of all (integer) vectors x ∈ a + LZ . +As an example, let consider the linear space LR and the lattice LZ both spanned +by the two vectors (1, −2, 1, 0) and (2, −3, −0, 1). Moreover, consider the sign- +constraints (1, 2, 2, 0). Thus, we are looking for a finite explicit sign-compatible +description for all x that can be written as +   + 1 2 +  −2 −3  + x=  λ, +   +  1 0  + 0 1 + + 23 +2.1. Affine systems and their encodings 24 + + +with λ ∈ R2 and λ ∈ Z2 , respectively. +In order to solve this affine system using zsolve, we create the following input files +to encode the affine system: + + affine.lat affine.sign + 1 4 + 2 4 + 1 2 2 0 + 1 −1 1 0 + 2 −3 0 1 + + +and then call + + ./zsolve affine + +This creates the files affine.zhom and affine.zinhom. +Chapter 3 + +Command-line reference + +3.1 circuits +Usage: circuits [options] PROJECT + +Computes the circuits of a cone. + +Input Files: + PROJECT.mat A matrix (compulsory). + PROJECT.sign The sign constraints of the variables (’1’ means + non-negative, ’0’ means a free variable, and ’2’ means + both non-negative and non-positive). + It is optional, and the default is both. + PROJECT.rel The relations on the matrix rows (’<’,’>’,’=’). + It is optional and the default is all ’=’. + The mat must be given with this file. +Output Files: + PROJECT.cir The circuits of the cone. + PROJECT.qfree A basis for the linear subspace of the cone. + If this file does not exist then the linear subspace + is trivial. + +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + + 25 +3.1. circuits 26 + + + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -m, --mat Use the Matrix algorithm (default for 32 and 64). + -s, --support Use the Support algorithm (default for arbitrary). + -o, --order=ORDERING Set ORDERING as the ordering in which the columns + are chosen. The possible orderings are ‘maxinter’, + ‘minindex’, ‘maxcutoff’ (default), and ‘mincutoff’. + -f, --output-freq=n Set the frequency of output (default is 1000). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +Chapter 3. Command-line reference 27 + + +3.2 genmodel + +usage: genmodel [--options] FILENAME + +Computes the problem matrix corresponding to graphical statistical models +given by a simplicial complex and levels on the nodes. + +Options: + -q, --quiet No output is written to the screen + +Input file: +FILENAME.mod Simplicial complex and levels on the nodes + +Output file: +FILENAME.mat Matrix file + +Example: Consider the problem of 3x3x3 tables with 2-marginals. These +are given by K_3 as the simplicial complex on 3 nodes and with levels +of 3 on each node. In ’333.mod’ write: +3 +3 3 3 +3 +2 1 2 +2 2 3 +2 3 1 +Calling ’genmodel 333’ produces the following file ’333.mat’: +27 27 +1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 +0 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 +[...] +1 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +0 1 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +0 0 1 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +[...] +1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +3.2. genmodel 28 + + +[...] +Chapter 3. Command-line reference 29 + + +3.3 gensymm +usage: gensymm [--options] A B C D FILENAME + +Computes the generators for the symmetry group acting on 4-way tables +with 3-marginals. By putting one side length to 1, this includes +3-way tables with 2-marginals. + +Options: + -q, --quiet No output is written to the screen + +Output file: + FILENAME.sym generators for the symmetry group + +Example: Consider the problem of 3x3x3 tables with 2-marginals. Calling + gensymm 3 3 3 1 333 +produces the file ’333.sym’ containing the following lines. + +9 27 +10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 1 2 3 4 5 6 7 8 9 +10 11 12 13 14 15 16 17 18 1 2 3 4 5 6 7 8 9 19 20 21 22 23 24 25 26 27 +4 5 6 7 8 9 1 2 3 13 14 15 16 17 18 10 11 12 22 23 24 25 26 27 19 20 21 +4 5 6 1 2 3 7 8 9 13 14 15 10 11 12 16 17 18 22 23 24 19 20 21 25 26 27 +2 3 1 5 6 4 8 9 7 11 12 10 14 15 13 17 18 16 20 21 19 23 24 22 26 27 25 +2 1 3 5 4 6 8 7 9 11 10 12 14 13 15 17 16 18 20 19 21 23 22 24 26 25 27 +1 2 3 10 11 12 19 20 21 4 5 6 13 14 15 22 23 24 7 8 9 16 17 18 25 26 27 +1 10 19 4 13 22 7 16 25 2 11 20 5 14 23 8 17 26 3 12 21 6 15 24 9 18 27 +1 4 7 2 5 8 3 6 9 10 13 16 11 14 17 12 15 18 19 22 25 20 23 26 21 24 27 +3.4. graver 30 + + +3.4 graver + +Usage: graver [options] PROJECT + +Computes the Graver basis of a matrix or a given lattice. + +Basic options: + -p PREC, --precision=PREC Use precision (32, 64, gmp). Default is 32 bit + -m, --maxnorm Write vectors with maximum norm to PROJECT.maxnorm + -b [FREQ], --backup[=FREQ] Frequently backup status to PROJECT.backup + -r, --resume Resume from backup file PROJECT.backup + -h, --help Display this help + --version Display version information + +Output options: + -q, --quiet Quiet mode + -u, --update[=1] Updated output on console (default) + -uu, --update=2 More verbose updated output on console + -v, --verbose[=1] Output once every variable computation + -vv, --verbose=2 Output once every norm sum computation + -vvv, --verbose=3 Output once every norm computation + +Logging options: + -n, --log=0 Disable logging (default) + -l, --log[=1] Log once every variable computation to PROJECT.log + -ll, --log=2 Log once every norm sum computation to PROJECT.log + -lll, --log=3 Log once every norm computation to PROJECT.log + +Input files: +PROJECT.mat Matrix +PROJECT.lat Lattice basis (can be provided instead of matrix) +PROJECT.sign Sign of columns (optional) +PROJECT.lb Lower bounds of columns (optional) +PROJECT.ub Upper bounds of columns (optional) + +Backup files: +Chapter 3. Command-line reference 31 + + +PROJECT.backup Backup file +PROJECT.backup~ Temporary backup file + (if it exists, it may be newer than PROJECT.backup) + +Output files: +PROJECT.gra Graver basis +PROJECT.zfree Free part of the solution +PROJECT.maxnorm Vectors with maximum norm (if -m, --maxnorm is in use) +3.5. groebner 32 + + +3.5 groebner + +Usage: groebner [options] PROJECT + +Computes a Groebner basis of the toric ideal of a matrix, +or, more general, of the lattice ideal of a lattice. + +Input Files: + PROJECT.mat A matrix (optional if lattice basis is given). + PROJECT.lat A lattice basis (optional if matrix is given). + PROJECT.cost The cost matrix, which determines the term ordering + (optional, default is degrevlex). + Ties are broken with degrevlex. + PROJECT.sign The sign constraints of the variables (’1’ means + non-negative and ’0’ means a free variable). + It is optional, and the default is all non-negative. + PROJECT.mar The Markov basis/generating set of the lattice (optional). + PROJECT.weights The weight vectors used for truncation (optional). + PROJECT.weights.max The maximum weights used for truncation. + This file is needed when PROJECT.weights exists. + PROJECT.zsol An integer solution to specify a fiber (optional). + The integer solution is used for truncation. +Output Files: + PROJECT.gro The Groebner basis of the lattice. + +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -a, --algorithm=ALG Select ALG as the completion procedure for + computing Groebner bases. ALG is one of + ‘fifo’, ‘weighted’, or ’unbounded.’ + -g, --generation=ALG Select ALG as the procedure for computing + a generating set or Markov basis. ALG is + one of ‘hybrid’ (default), ‘project-and-lift’, + ‘max-min’, or ’saturation’. +Chapter 3. Command-line reference 33 + + + -t, --truncation=TRUNC Set TRUNC as the truncation method. TRUNC is + of the following: ‘ip’, ‘lp’, ‘weight’ (default), + or ‘none’. Only relevant if ‘zsol’ is given. + -m, --minimal=STATE If STATE is ‘yes’ (default), then 4ti2 will + compute a minimal Markov basis. If STATE is + ’no’, then the Markov basis will not + necessarily be minimal. + -r, --auto-reduce-freq=n Set the frequency of auto reduction. + (default is 2500). + -f, --output-freq=n Set the frequency of output (default is 1000). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +3.6. hilbert 34 + + +3.6 hilbert + +Usage: hilbert [options] PROJECT + +Computes the Hilbert basis of a matrix or a given lattice. + +Basic options: + -p PREC, --precision=PREC Use precision (32, 64, gmp). Default is 32 bit + -m, --maxnorm Write vectors with maximum norm to PROJECT.maxnorm + -b [FREQ], --backup[=FREQ] Frequently backup status to PROJECT.backup + -r, --resume Resume from backup file PROJECT.backup + -h, --help Display this help + --version Display version information + +Output options: + -q, --quiet Quiet mode + -u, --update[=1] Updated output on console (default) + -uu, --update=2 More verbose updated output on console + -v, --verbose[=1] Output once every variable computation + -vv, --verbose=2 Output once every norm sum computation + -vvv, --verbose=3 Output once every norm computation + +Logging options: + -n, --log=0 Disable logging (default) + -l, --log[=1] Log once every variable computation to PROJECT.log + -ll, --log=2 Log once every norm sum computation to PROJECT.log + -lll, --log=3 Log once every norm computation to PROJECT.log + +Input files: +PROJECT.mat Matrix +PROJECT.lat Lattice basis (can be provided instead of matrix) +PROJECT.rel Relations (<, >, =) +PROJECT.sign Sign of columns (optional) +PROJECT.ub Upper bounds of columns (optional) + +Backup files: +Chapter 3. Command-line reference 35 + + +PROJECT.backup Backup file +PROJECT.backup~ Temporary backup file + (if it exists, it may be newer than PROJECT.backup) + +Output files: +PROJECT.hil Hilbert basis +PROJECT.zfree Free part of the solution +PROJECT.maxnorm Vectors with maximum norm (if -m, --maxnorm is in use) +3.7. markov 36 + + +3.7 markov + +Usage: markov [options] PROJECT + +Computes a Markov basis (generating set) of the toric ideal +of a matrix or, more general, of the lattice ideal of a lattice. + +Input Files: + PROJECT A matrix (optional only if lattice basis is given). + PROJECT.lat A lattice basis (optional only if matrix is given). + PROJECT.sign The sign constraints of the variables (’1’ means + non-negative and ’0’ means a free variable). + It is optional, and the default is all non-negative. + PROJECT.weights The weight vectors used for truncation (optional). + PROJECT.weights.max The maximum weights used for truncation. + This file is needed when PROJECT.weights exists. + PROJECT.zsol An integer solution to specify a fiber (optional). + The integer solution is used for truncation. +Output Files: + PROJECT.mar The Markov basis/generating set of the lattice. +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -a, --algorithm=ALG Select ALG as the completion procedure for + computing Groebner bases. ALG is one of + ‘fifo’, ‘weighted’, or ’unbounded.’ + -g, --generation=ALG Select ALG as the procedure for computing + a generating set or Markov basis. ALG is + one of ‘hybrid’ (default), ‘project-and-lift’, + ‘max-min’, or ’saturation’. + -t, --truncation=TRUNC Set TRUNC as the truncation method. TRUNC is + of the following: ‘ip’, ‘lp’, ‘weight’ (default), + or ‘none’. Only relevant if ‘zsol’ is given. + -m, --minimal=STATE If STATE is ‘yes’ (default), then 4ti2 will + compute a minimal Markov basis. If STATE is +Chapter 3. Command-line reference 37 + + + ’no’, then the Markov basis will not + necessarily be minimal. + -r, --auto-reduce-freq=n Set the frequency of auto reduction. + (default is 2500). + -f, --output-freq=n Set the frequency of output (default is 1000). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +3.8. minimize 38 + + +3.8 minimize +Usage: minimize [options] PROJECT + +Computes the minimal solution of an integer linear program +or, more general, a lattice program, using a Groebner basis. + +Input Files: + PROJECT.mat A matrix (optional only if lattice basis is given). + PROJECT.lat A lattice basis (optional only if matrix is given). + PROJECT.cost The cost vector. Exactly one vector allowed. + PROJECT.zsol An integer solution to specify a fiber (needed). + PROJECT.sign The sign constraints of the variables (’1’ means + non-negative and ’0’ means a free variable). + It is optional, and the default is all non-negative. +Output Files: + PROJECT.min The minimal solution for the given fiber. + +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -a, --algorithm=ALG Select ALG as the completion procedure for + computing Groebner bases. ALG is one of + ‘fifo’, ‘weighted’, or ’unbounded.’ + -t, --truncation=TRUNC Set TRUNC as the truncation method. TRUNC is + of the following: ‘ip’, ‘lp’, ‘weight’ (default), + or ‘none’. Only relevant if ‘zsol’ is given. + -r, --auto-reduce-freq=n Set the frequency of auto reduction. + (default is 2500). + -f, --output-freq=n Set the frequency of output (default is 1000). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +Chapter 3. Command-line reference 39 + + +3.9 normalform +Usage: normalform [options] PROJECT + +Computes the normal form of a list of feasible points. + +Input Files: + PROJECT.mat A matrix (optional if lattice basis is given). + PROJECT.lat A lattice basis (optional if matrix is given). + PROJECT.gro The Groebner basis of the lattice (needed). + PROJECT.cost The cost matrix (optional, default is degrevlex). + Ties are broken with degrevlex. + PROJECT.feas An list of integer feasible solutions (needed). + PROJECT.sign The sign constraints of the variables (’1’ means + non-negative and ’0’ means a free variable). + It is optional, and the default is all non-negative. +Output Files: + PROJECT.nf The normal forms of the feasible solutions. + +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +3.10. output 40 + + +3.10 output + +usage: output [--options] FILENAME.EXT + +Transforms a 4ti2 matrix file to something else. + +General options: + --quiet No output is written to the screen. + +Options that control what to output: their output files: + --binomials Write vectors as binomials. FILENAME.EXT.bin + Use an optional input file + ’FILENAME.EXT.vars’ + to specify variable names. + + --maple Write vectors as Maple list. FILENAME.EXT.maple + This format is suitable also for + CoCoA, Mathematica, Macaulay2. + + --0-1 Extract vectors with 0-1 + components only. FILENAME.EXT.0-1 + + --transpose Transpose matrix and write it FILENAME.EXT.tra + in 4ti2 format. + + --degree Print 1-norms of all vectors. + + --degree N Extract all vectors of 1-norm FILENAME.EXT.deg.N + equal to N. + + --degree N1 N2 Extract all vectors of 1-norm FILENAME.EXT.deg.N1-N2 + between N1 and N2 (inclusive). + + --support Print supports of all vectors. + + --support S Extract all vectors of support FILENAME.EXT.supp.S +Chapter 3. Command-line reference 41 + + + size equal to S. + + --support S1 S2 Extract all vectors of support FILENAME.EXT.supp.S1-S2 + size between S1 and S2 (incl.) + + --positive Extract positive parts of vectors. FILENAME.EXT.pos + Corresponds to leading terms of + binomials. + + --3way A B C Write vectors as 3-way tables FILENAME.EXT.3way + of size A x B x C. + + --nonzero-at K Extract all vectors that have FILENAME.EXT.nonzero.K + nonzero K-th coordinate. + +Undocumented or obscure options for experts: + --representatives + --dominated Extract all non-dominated vectors FILENAME.EXT.nondom + --maximal-non-dominated FILENAME.EXT.maxnondom + --expand-representatives-to-full-orbits + --type T + --AxB Computes a matrix-vector product. + --macaulay2 + --mathematica + --cocoa + --sum Print the sum of the columns. + --submatrix LISTFILENAME FILENAME.EXT.submat + --remove-column I FILENAME.EXT.remcol + --remcol I FILENAME.EXT.remcol + --stabilizer SYMMFILENAME FILENAME.EXT.stab + --fill-column FILENAME.EXT.fil + --add-column FILENAME.EXT.addcol + --fix I1 ... IK Extract fixed vectors, FILENAME.EXT.fix + that is, those vectors that + have x[i]=i for the given i. + --fox I1 ... IK Extract relaxed fixed vectors. FILENAME.EXT.fox +3.10. output 42 + + + --initial-forms Extract initial forms. FILENAME.ini + (Call with FILENAME rather FILENAME.ini.bin + than FILENAME.EXT. Reads + FILENAME.gro and + optionally FILENAME.cost and + FILENAME.vars. + +Examples: + ’output --binomials file.gra’ writes the Graver basis elements as + binomials in ’file.gra.bin’. + + ’output --0-1 foo.gra’ extracts the 0-1 elements from the Graver basis + elements and writes them into ’foo.gra.0-1’. +Chapter 3. Command-line reference 43 + + +3.11 ppi +usage: ppi [--binary-output] N + +Computes the primitive partition identities, that is, the Graver basis of [1 2 3 ... N]. + +Options: + -b, --binary-output Create a binary file ppiN.dat instead of text file ppiN.gra +3.12. qsolve 44 + + +3.12 qsolve +Usage: qsolve [options] PROJECT + +Computes a generator description of a cone. + +Input Files: + PROJECT.mat A matrix (compulsory). + PROJECT.sign The sign constraints of the variables (’1’ means + non-negative, ’0’ means a free variable, and ’2’ means + both non-negative and non-positive). + It is optional, and the default is all free. + PROJECT.rel The relations on the matrix rows (’<’,’>’,’=’). + It is optional and the default is all ’=’. + The mat must be given with this file. +Output Files: + PROJECT.qhom The homogeneous generators of the linear system. + PROJECT.qfree A basis for the linear subspace of the cone. + If this file does not exist then the linear subspace + is trivial. + +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -m, --mat Use the Matrix algorithm (default for 32 and 64). + -s, --support Use the Support algorithm (default for arbitrary). + -o, --order=ORDERING Set ORDERING as the ordering in which the columns + are chosen. The possible orderings are ‘maxinter’, + ‘minindex’, ‘maxcutoff’ (default), and ‘mincutoff’. + -f, --output-freq=n Set the frequency of output (default is 1000). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +Chapter 3. Command-line reference 45 + + +3.13 rays +Usage: rays [options] PROJECT + +Computes the extreme rays of a cone. + +Input Files: + PROJECT.mat A matrix (compulsory). + PROJECT.sign The sign constraints of the variables (’1’ means + non-negative, ’0’ means a free variable, and ’2’ means + both non-negative and non-positive). + It is optional, and the default is all non-negative. + PROJECT.rel The relations on the matrix rows (’<’,’>’,’=’). + It is optional and the default is all ’=’. + The mat must be given with this file. +Output Files: + PROJECT.ray The extreme rays of the cone. + PROJECT.qfree A basis for the linear subspace of the cone. + If this file does not exist then the linear subspace + is trivial. + +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -m, --mat Use the Matrix algorithm (default for 32 and 64). + -s, --support Use the Support algorithm (default for arbitrary). + -o, --order=ORDERING Set ORDERING as the ordering in which the columns + are chosen. The possible orderings are ‘maxinter’, + ‘minindex’, ‘maxcutoff’ (default), and ‘mincutoff’. + -f, --output-freq=n Set the frequency of output (default is 1000). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +3.14. walk 46 + + +3.14 walk +Usage: walk [options] PROJECT + +Computes the minimal solution of an integer linear program +or, more general, a lattice program using a Groebner basis. + +Input Files: + PROJECT.mat A matrix (optional only if lattice basis is given). + PROJECT.lat A lattice basis (optional only if matrix is given). + PROJECT.gro.start The starting Groebner basis (needed). + PROJECT.gro.cost The starting cost vector (optional, default is degrevlex). + Ties are broken with degrevlex. + PROJECT.cost The target cost vector (optional, default is degrevlex). + Ties are broken with degrevlex. + PROJECT.zsol An integer solution to specify a fiber (needed). + PROJECT.sign The sign constraints of the variables (’1’ means + non-negative and ’0’ means a free variable). + It is optional, and the default is all non-negative. +Output Files: + PROJECT.gro The Groebner basis of the lattice. + +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -t, --truncation=TRUNC Set TRUNC as the truncation method. TRUNC is + of the following: ‘ip’, ‘lp’, ‘weight’ (default), + or ‘none’. Only relevant if ‘zsol’ is given. + -f, --output-freq=n Set the frequency of output (default is 1000). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +Chapter 3. Command-line reference 47 + + +3.15 zbasis +Usage: zbasis [options] PROJECT + +Computes an integer lattice basis. + +Input Files: + PROJECT A matrix (needed). +Output Files: + PROJECT.lat A lattice basis. +Options: + -p, --precision=PREC Select PREC as the integer arithmetic precision. + PREC is one of the following: ‘64’ (default), + ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). + -q, --quiet Do not output anything to the screen. + -h, --help Display this help and exit. +3.16. zsolve 48 + + +3.16 zsolve + +Usage: zsolve [options] PROJECT + +Solves linear inequality and equation systems over the integers. + +Basic options: + -p PREC, --precision=PREC Use precision (32, 64, gmp). Default is 32 bit + -m, --maxnorm Write vectors with maximum norm to PROJECT.maxnorm + -b [FREQ], --backup[=FREQ] Frequently backup status to PROJECT.backup + -r, --resume Resume from backup file PROJECT.backup + -h, --help Display this help + --version Display version information + +Output options: + -q, --quiet Quiet mode + -u, --update[=1] Updated output on console (default) + -uu, --update=2 More verbose updated output on console + -v, --verbose[=1] Output once every variable computation + -vv, --verbose=2 Output once every norm sum computation + -vvv, --verbose=3 Output once every norm computation + +Logging options: + -n, --log=0 Disable logging (default) + -l, --log[=1] Log once every variable computation to PROJECT.log + -ll, --log=2 Log once every norm sum computation to PROJECT.log + -lll, --log=3 Log once every norm computation to PROJECT.log + +Input files: +PROJECT.mat Matrix +PROJECT.lat Lattice basis (can be provided instead of matrix) +PROJECT.rhs Right hand side +PROJECT.rel Relations (<, >, =) +PROJECT.sign Sign of columns (optional) +PROJECT.lb Lower bounds of columns (optional) +PROJECT.ub Upper bounds of columns (optional) +Chapter 3. Command-line reference 49 + + + + +Backup files: +PROJECT.backup Backup file +PROJECT.backup~ Temporary backup file + (if it exists, it may be newer than PROJECT.backup) + +Output files: +PROJECT.zinhom Inhomogeneous part of the solution diff --git a/apn/lean/docs/4ti2/LICENSE b/apn/lean/docs/4ti2/LICENSE new file mode 100644 index 00000000..d511905c --- /dev/null +++ b/apn/lean/docs/4ti2/LICENSE @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/apn/lean/docs/csdp/LICENSE b/apn/lean/docs/csdp/LICENSE new file mode 100644 index 00000000..45977f0b --- /dev/null +++ b/apn/lean/docs/csdp/LICENSE @@ -0,0 +1,237 @@ +Common Public License Version 1.0 + +THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS COMMON +PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF +THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + +1. DEFINITIONS + +"Contribution" means: + + a) in the case of the initial Contributor, the initial code and + documentation distributed under this Agreement, and + + b) in the case of each subsequent Contributor: + + i) changes to the Program, and + + ii) additions to the Program; + + where such changes and/or additions to the Program originate from + and are distributed by that particular Contributor. A Contribution + 'originates' from a Contributor if it was added to the Program by + such Contributor itself or anyone acting on such Contributor's + behalf. Contributions do not include additions to the Program + which: (i) are separate modules of software distributed in + conjunction with the Program under their own license agreement, + and (ii) are not derivative works of the Program. + +"Contributor" means any person or entity that distributes the Program. + +"Licensed Patents " mean patent claims licensable by a Contributor +which are necessarily infringed by the use or sale of its Contribution +alone or when combined with the Program. + +"Program" means the Contributions distributed in accordance with this +Agreement. + +"Recipient" means anyone who receives the Program under this +Agreement, including all Contributors. + +2. GRANT OF RIGHTS + + a) Subject to the terms of this Agreement, each Contributor hereby + grants Recipient a non-exclusive, worldwide, royalty-free + copyright license to reproduce, prepare derivative works of, + publicly display, publicly perform, distribute and sublicense the + Contribution of such Contributor, if any, and such derivative + works, in source code and object code form. + + b) Subject to the terms of this Agreement, each Contributor hereby + grants Recipient a non-exclusive, worldwide, royalty-free patent + license under Licensed Patents to make, use, sell, offer to sell, + import and otherwise transfer the Contribution of such + Contributor, if any, in source code and object code form. This + patent license shall apply to the combination of the Contribution + and the Program if, at the time the Contribution is added by the + Contributor, such addition of the Contribution causes such + combination to be covered by the Licensed Patents. The patent + license shall not apply to any other combinations which include + the Contribution. No hardware per se is licensed hereunder. + + c) Recipient understands that although each Contributor grants the + licenses to its Contributions set forth herein, no assurances are + provided by any Contributor that the Program does not infringe the + patent or other intellectual property rights of any other entity. + Each Contributor disclaims any liability to Recipient for claims + brought by any other entity based on infringement of intellectual + property rights or otherwise. As a condition to exercising the + rights and licenses granted hereunder, each Recipient hereby + assumes sole responsibility to secure any other intellectual + property rights needed, if any. For example, if a third party + patent license is required to allow Recipient to distribute the + Program, it is Recipient's responsibility to acquire that license + before distributing the Program. + + d) Each Contributor represents that to its knowledge it has + sufficient copyright rights in its Contribution, if any, to grant + the copyright license set forth in this Agreement. + +3. REQUIREMENTS + +A Contributor may choose to distribute the Program in object code form +under its own license agreement, provided that: + + a) it complies with the terms and conditions of this Agreement; + and + + b) its license agreement: + + i) effectively disclaims on behalf of all Contributors all + warranties and conditions, express and implied, including + warranties or conditions of title and non-infringement, and + implied warranties or conditions of merchantability and fitness + for a particular purpose; + + ii) effectively excludes on behalf of all Contributors all + liability for damages, including direct, indirect, special, + incidental and consequential damages, such as lost profits; + + iii) states that any provisions which differ from this Agreement + are offered by that Contributor alone and not by any other party; + and + + iv) states that source code for the Program is available from such + Contributor, and informs licensees how to obtain it in a + reasonable manner on or through a medium customarily used for + software exchange. + +When the Program is made available in source code form: + + a) it must be made available under this Agreement; and + + b) a copy of this Agreement must be included with each copy of the + Program. + +Contributors may not remove or alter any copyright notices contained +within the Program. + +Each Contributor must identify itself as the originator of its +Contribution, if any, in a manner that reasonably allows subsequent +Recipients to identify the originator of the Contribution. + +4. COMMERCIAL DISTRIBUTION + +Commercial distributors of software may accept certain +responsibilities with respect to end users, business partners and the +like. While this license is intended to facilitate the commercial use +of the Program, the Contributor who includes the Program in a +commercial product offering should do so in a manner which does not +create potential liability for other Contributors. Therefore, if a +Contributor includes the Program in a commercial product offering, +such Contributor ("Commercial Contributor") hereby agrees to defend +and indemnify every other Contributor ("Indemnified Contributor") +against any losses, damages and costs (collectively "Losses") arising +from claims, lawsuits and other legal actions brought by a third party +against the Indemnified Contributor to the extent caused by the acts +or omissions of such Commercial Contributor in connection with its +distribution of the Program in a commercial product offering. The +obligations in this section do not apply to any claims or Losses +relating to any actual or alleged intellectual property +infringement. In order to qualify, an Indemnified Contributor must: a) +promptly notify the Commercial Contributor in writing of such claim, +and b) allow the Commercial Contributor to control, and cooperate with +the Commercial Contributor in, the defense and any related settlement +negotiations. The Indemnified Contributor may participate in any such +claim at its own expense. + +For example, a Contributor might include the Program in a commercial +product offering, Product X. That Contributor is then a Commercial +Contributor. If that Commercial Contributor then makes performance +claims, or offers warranties related to Product X, those performance +claims and warranties are such Commercial Contributor's responsibility +alone. Under this section, the Commercial Contributor would have to +defend claims against the other Contributors related to those +performance claims and warranties, and if a court requires any other +Contributor to pay any damages as a result, the Commercial Contributor +must pay those damages. + +5. NO WARRANTY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS +PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY +WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY +OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely +responsible for determining the appropriateness of using and +distributing the Program and assumes all risks associated with its +exercise of rights under this Agreement, including but not limited to +the risks and costs of program errors, compliance with applicable +laws, damage to or loss of data, programs or equipment, and +unavailability or interruption of operations. + +6. DISCLAIMER OF LIABILITY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR +ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING +WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR +DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED +HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +7. GENERAL + +If any provision of this Agreement is invalid or unenforceable under +applicable law, it shall not affect the validity or enforceability of +the remainder of the terms of this Agreement, and without further +action by the parties hereto, such provision shall be reformed to the +minimum extent necessary to make such provision valid and enforceable. + +If Recipient institutes patent litigation against a Contributor with +respect to a patent applicable to software (including a cross-claim or +counterclaim in a lawsuit), then any patent licenses granted by that +Contributor to such Recipient under this Agreement shall terminate as +of the date such litigation is filed. In addition, if Recipient +institutes patent litigation against any entity (including a +cross-claim or counterclaim in a lawsuit) alleging that the Program +itself (excluding combinations of the Program with other software or +hardware) infringes such Recipient's patent(s), then such Recipient's +rights granted under Section 2(b) shall terminate as of the date such +litigation is filed. + +All Recipient's rights under this Agreement shall terminate if it +fails to comply with any of the material terms or conditions of this +Agreement and does not cure such failure in a reasonable period of +time after becoming aware of such noncompliance. If all Recipient's +rights under this Agreement terminate, Recipient agrees to cease use +and distribution of the Program as soon as reasonably +practicable. However, Recipient's obligations under this Agreement and +any licenses granted by Recipient relating to the Program shall +continue and survive. + +Everyone is permitted to copy and distribute copies of this Agreement, +but in order to avoid inconsistency the Agreement is copyrighted and +may only be modified in the following manner. The Agreement Steward +reserves the right to publish new versions (including revisions) of +this Agreement from time to time. No one other than the Agreement +Steward has the right to modify this Agreement. IBM is the initial +Agreement Steward. IBM may assign the responsibility to serve as the +Agreement Steward to a suitable separate entity. Each new version of +the Agreement will be given a distinguishing version number. The +Program (including Contributions) may always be distributed subject to +the version of the Agreement under which it was received. In addition, +after a new version of the Agreement is published, Contributor may +elect to distribute the Program (including its Contributions) under +the new version. Except as expressly stated in Sections 2(a) and 2(b) +above, Recipient receives no rights or licenses to the intellectual +property of any Contributor under this Agreement, whether expressly, +by implication, estoppel or otherwise. All rights in the Program not +expressly granted under this Agreement are reserved. + +This Agreement is governed by the laws of the State of New York and +the intellectual property laws of the United States of America. No +party to this Agreement will bring a legal action under this Agreement +more than one year after the cause of action arose. Each party waives +its rights to a jury trial in any resulting litigation. diff --git a/apn/lean/docs/csdp/csdp-user-guide.txt b/apn/lean/docs/csdp/csdp-user-guide.txt new file mode 100644 index 00000000..d5735eaf --- /dev/null +++ b/apn/lean/docs/csdp/csdp-user-guide.txt @@ -0,0 +1,335 @@ + + + CSDP 6.2.0 User’s Guide + Brian Borchers + July 24, 2017 + + +Introduction +CSDP is a software package for solving semidefinite programming problems. The +algorithm is a predictor–corrector version of the primal–dual barrier method of +Helmberg, Rendl, Vanderbei, and Wolkowicz [4]. A more detailed, but now +somewhat outdated description of the algorithms in CSDP can be found in [1]. +CSDP is written in C for efficiency and portability. On systems with multiple +processors and shared memory, CSDP can run in parallel. CSDP uses OpenMP +directives in the C source code to tell the compiler how to parallelize various +loops. The parallel implementation is described in [2]. The code is designed +to make use of highly optimized linear algebra routines from the LAPACK and +BLAS libraries. + CSDP also has a number of features that make it flexible. CSDP can work +with general symmetric matrices or with matrices that have defined block di- +agonal structure. CSDP is designed to handle constraint matrices with general +sparse structure. The code takes advantage of this structure in efficiently con- +structing the system of equations that is solved at each iteration of the algo- +rithm. + In addition to its default termination criteria, CSDP includes a feature that +allows the user to terminate the solution process after any iteration. For exam- +ple, this feature has been used within a branch and bound code for maximum +independent set problems to terminate the bounding calculations as soon as a +bound has been obtained that is good enough to fathom the current note. The +library also contains routines for writing SDP problems and solutions to files +and reading problems and solutions from files. + A stand alone solver program is included for solving SDP problems that have +been written in the SDPA sparse format [3]. An interface to MATLAB and the +open source MATLAB clone Octave is also provided. This interface can be used +to solve problems that are in the format used by the SeDuMi [6]. + This document describes how to use the stand alone solver, MATLAB and +Octave interface, and library routines. For detailed instructions on how to +compile and install CSDP see the INSTALL file in the main directory. + + + + +The SDP Problem +CSDP solves semidefinite programming problems of the form + + max tr (CX) + A(X) = a (1) + X  0 + +where   + tr (A1 X) +  tr (A2 X)  + A(X) =  . (2) +  ...  + tr (Am X) +Here X  0 means that X is positive semidefinite. All of the matrices Ai , X, +and C are assumed to be real and symmetric. + The dual of this SDP is + min aT y + T + A (y) − C = Z (3) + Z  0 + +where + m + X + AT (y) = y i Ai . (4) + i=1 + + Other semidefinite programming packages use slight variations on this primal– +dual pair. For example, the primal–dual pair used in SDPA interchanges the +primal and dual problems. + Users of CSDP can specify their own termination criteria. However, the +default criteria are that + tr(XZ) < 1.0 × 10−8 + 1+|aT y|+|tr(CX)| + kA(x)−ak2 + 1+kak2 < 1.0 × 10−8 + T + (5) + kA (y)−C−ZkF + 1+kCkF < 1.0 × 10−8 + X, Z  0. + + Note that for feasible primal and dual solutions, aT y − tr(CX) = tr(XZ). +Thus the first of these criteria insures that the relative duality gap is small. In +practice, there are sometimes solutions which satisfy our primal and dual feasi- +bility tolerances but have duality gaps which are not close to tr(XZ). In some +cases, the duality gap may even become negative. Because of this ambiguity, we +use the tr(XZ) gap instead of the difference between the objective functions. +An option in the param.csdp file allows CSDP to use the difference of the primal +objective functions instead of the tr(XZ) gap. + The matrices X and Z are considered to be positive definite when their +Cholesky factorizations can be computed. In practice, this is somewhat more +conservative than simply requiring all eigenvalues to be nonnegative. + + + The Seventh DIMACS Implementation Challenge used a slightly different +set of error measures [5]. For convenience in benchmarking, CSDP includes +these DIMACS error measures in its output. + To test for primal infeasibility, CSDP checks the inequality + + −aT y + > 1.0 × 108 . (6) + kAT (y) − ZkF + +If CSDP detects that a problem is primal infeasible, then it will announce this +in its output and return a dual solution with aT y = −1, and kAT (y) − Zk very +small. This acts as a certificate of primal infeasibility. + Similarly, CSDP tests for dual infeasibility by checking + + tr(CX) + > 1.0 × 108 . (7) + kA(X)k2 + +If CSDP detects that a problem is dual infeasible, it announces this in its output +and returns a primal solution with tr(CX) = 1, and kA(X)k small. This acts +as a certificate of the dual infeasibility. + The tolerances for primal and dual feasibility and the relative duality gap +can be changed by editing CSDP’s parameter file. See the following section on +using the stand alone solver for a description of this parameter file. + + +Using the stand alone solver +CSDP includes a program which can be used to solve SDP’s that have been +written in the SDPA sparse format. Usage is + csdp [] [] + +where is the name of a file containing the SDP problem in +SDPA sparse format, final solution is the optional name of a file in which +to save the final solution, and initial solution is the optional name of a file +from which to take the initial solution. + The following example shows how CSDP would be used to solve a test prob- +lem. + +>csdp theta1.dat-s +CSDP 6.2.0 +Iter: 0 Ap: 0.00e+00 Pobj: 1.4644661e+04 Ad: 0.00e+00 Dobj: 0.0000000e+00 +Iter: 1 Ap: 9.31e-01 Pobj: 5.7513865e+03 Ad: 1.00e+00 Dobj: 8.0172003e+01 +Iter: 2 Ap: 9.21e-01 Pobj: 2.3227402e+02 Ad: 1.00e+00 Dobj: 8.2749235e+01 +Iter: 3 Ap: 9.30e-01 Pobj: 1.0521019e+01 Ad: 1.00e+00 Dobj: 8.4447722e+01 +Iter: 4 Ap: 1.00e+00 Pobj: 2.5047625e+00 Ad: 1.00e+00 Dobj: 7.2126480e+01 +Iter: 5 Ap: 1.00e+00 Pobj: 7.5846337e+00 Ad: 1.00e+00 Dobj: 4.2853659e+01 +Iter: 6 Ap: 1.00e+00 Pobj: 1.5893126e+01 Ad: 1.00e+00 Dobj: 3.0778169e+01 +Iter: 7 Ap: 1.00e+00 Pobj: 1.9887401e+01 Ad: 1.00e+00 Dobj: 2.4588662e+01 + + +Iter: 8 Ap: 1.00e+00 Pobj: 2.1623330e+01 Ad: 1.00e+00 Dobj: 2.3465172e+01 +Iter: 9 Ap: 1.00e+00 Pobj: 2.2611983e+01 Ad: 1.00e+00 Dobj: 2.3097049e+01 +Iter: 10 Ap: 1.00e+00 Pobj: 2.2939498e+01 Ad: 1.00e+00 Dobj: 2.3010908e+01 +Iter: 11 Ap: 1.00e+00 Pobj: 2.2996259e+01 Ad: 1.00e+00 Dobj: 2.3000637e+01 +Iter: 12 Ap: 1.00e+00 Pobj: 2.2999835e+01 Ad: 1.00e+00 Dobj: 2.3000020e+01 +Iter: 13 Ap: 1.00e+00 Pobj: 2.2999993e+01 Ad: 1.00e+00 Dobj: 2.2999999e+01 +Iter: 14 Ap: 1.00e+00 Pobj: 2.3000000e+01 Ad: 1.00e+00 Dobj: 2.3000000e+01 +Success: SDP solved +Primal objective value: 2.3000000e+01 +Dual objective value: 2.3000000e+01 +Relative primal infeasibility: 5.55e-17 +Relative dual infeasibility: 3.93e-09 +Real Relative Gap: 7.21e-09 +XZ Relative Gap: 7.82e-09 +DIMACS error measures: 5.55e-17 0.00e+00 1.00e-07 0.00e+00 7.21e-09 7.82e-09 +Elements time: 0.001091 +Factor time: 0.000620 +Other time: 0.016636 +Total time: 0.018348 + One line of output appears for each iteration of the algorithm, giving the +iteration number, primal step size (Ap), primal objective value (Pobj), dual step +size (Ad), and dual objective value (Dobj). The last eight lines of output show +the primal and dual optimal objective values, the XZ duality gap, the actual +duality gap, the relative primal and dual infeasibility in the optimal solution. + The last four lines give the time in seconds used by various steps in the +algorithm. The first line, “Elements” shows the time spent in constructing the +Schur complement matrix. The second line, “Factor” shows the time spent in +factoring the Schur complement matrix. The third line, “Other” shows the time +spent in all other operations. The fourth line gives the total time used in solving +the problem. Note that the times given here are “wall clock” times, not CPU +time. On a system that is running other programs, the wall clock time may be +considerably larger than the CPU time. On multiprocessor systems, the wall +clock time will not include all of the CPU time used by the different processors. +The reported time will typically vary on repeated runs of CSDP, particularly +for small problems like the one solved here. + CSDP searches for a file named “param.csdp” in the current directory. If +no such file exists, then default values for all of CSDP’s parameters are used. If +there is a parameter file, then CSDP reads the parameter values from this file. +A sample file containing the default parameter values is given below. + +axtol=1.0e-8 +atytol=1.0e-8 +objtol=1.0e-8 +pinftol=1.0e8 +dinftol=1.0e8 + + +maxiter=100 +minstepfrac=0.90 +maxstepfrac=0.97 +minstepp=1.0e-8 +minstepd=1.0e-8 +usexzgap=1 +tweakgap=0 +affine=0 +printlevel=1 +perturbobj=1 +fastmode=0 + + The first three parameters, axtol, atytol, and objtol are the tolerances +for primal feasibility, dual feasibility, and relative duality gap. The parameters +pinftol and dinftol are tolerances used in determining primal and dual infea- +sibility. The maxiter parameter is used to limit the total number of iterations +that CSDP may use. The minstepfrac and maxstepfrac parameters deter- +mine how close to the edge of the feasible region CSDP will step. If the primal +or dual step is shorter than minstepp or minstepd, then CSDP declares a +line search failure. If parameter usexzgap is 0, then CSDP will use the ob- +jective function duality gap instead of the tr(XZ) gap. If tweakgap is set to +1, and usexzgap is set to 0, then CSDP will attempt to “fix” negative duality +gaps. If parameter affine is set to 1, then CSDP will take only primal–dual +affine steps and not make use of the barrier term. This can be useful for some +problems that do not have feasible solutions that are strictly in the interior of +the cone of semidefinite matrices. The printlevel parameter determines how +much debugging information is output. Use printlevel=0 for no output and +printlevel=1 for normal output. Higher values of printlevel will generate +more debugging output. The perturbobj parameter determines whether the +objective function will be perturbed to help deal with problems that have un- +bounded optimal solution sets. If perturbobj is 0, then the objective will not +be perturbed. If perturbobj is 1, then the objective function will be perturbed +by a default amount. Larger values of perturbobj (e.g. 100.0) increase the size +of the perturbation. This can be helpful in solving some difficult problems. The +fastmode parameter determines whether or not CSDP will skip certain time +consuming operations that slightly improve the accuracy of the solutions. If +fastmode is set to 1, then CSDP may be somewhat faster, but also somewhat +less accurate. + + + +SDPA sparse format example +========================== + For an example of how to setup these data structures, refer to the example +directory in the CSDP distribution. This directory contains a program that +solves the very small SDP + + max tr (CX) + tr A1 X = 1 + (8) + tr A2 X = 2 + X  0 +where   + 2 1 +  1 2  +   +  +  3 0 1  +  + C= +  0 2 0  +  (9) +  +  1 0 3  +  +  0  +   + 3 1 +  1 3  +   +  +  0 0 0  +  + A1 =  +  0 0 0  +  (10) +  +  0 0 0  +  +  1  + + + + +   + 0 0 +  0 0  +   +  +  3 0 1  +  + A2 =  +  0 4 0 . +  (11) +  +  1 0 5  +  +  0  + In this problem, the X, Z, A1 , A2 and C matrices have three blocks. The +first block is a 2 by 2 matrix. The second block is a 3 by 3 matrix. The third +block is a diagonal block with 2 entries. + In addition to setting up and solving this problem, the example program +calls the write prob() routine to produce a file containing the SDP problem in +SDPA sparse format. This is stored in the file prob.dat-s. + +2 +3 +2 3 -2 +1.000000000000000000e+00 2.000000000000000000e+00 +0 1 1 1 2.000000000000000000e+00 +0 1 1 2 1.000000000000000000e+00 +0 1 2 2 2.000000000000000000e+00 +0 2 1 1 3.000000000000000000e+00 +0 2 1 3 1.000000000000000000e+00 +0 2 2 2 2.000000000000000000e+00 +0 2 3 3 3.000000000000000000e+00 +1 1 1 1 3.000000000000000000e+00 +1 1 1 2 1.000000000000000000e+00 +1 1 2 2 3.000000000000000000e+00 +1 3 1 1 1.000000000000000000e+00 +2 2 1 1 3.000000000000000000e+00 +2 2 2 2 4.000000000000000000e+00 +2 2 3 3 5.000000000000000000e+00 +2 2 1 3 1.000000000000000000e+00 +2 3 2 2 1.000000000000000000e+00 + +The 2 in the first line indicates that this problem has two constraints. The 3 in +the second line indicates that there are three blocks in the X and Z matrices. +The third line gives the sizes of the three blocks. Note that the third block’s +size is given as -2. The minus sign indicates that this is a diagonal block. The +fourth line gives the values of the right hand sides of the two constraints. + The remaining lines in the file describe the entries in the C, A1 , and A2 +matrices. The first number in each line is the number of the matrix, with 0 +for the C matrix. The second number specifies a block within the matrix. The +third and fourth numbers give the row and column of a nonzero entry within +this block. The fifth number gives the actual value at that position within the + + + + +block. Comparing this file to the problem statement above can be helpful in diff --git a/apn/lean/docs/loogle/LICENSE b/apn/lean/docs/loogle/LICENSE new file mode 100644 index 00000000..813da297 --- /dev/null +++ b/apn/lean/docs/loogle/LICENSE @@ -0,0 +1,71 @@ +Apache License 2.0 (Apache) +Apache License +Version 2.0, January 2004 +http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + +"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. + +"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. + +"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. + +"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. + +"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. + +"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. + +"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). + +"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. + +"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." + +"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. + +2. Grant of Copyright License. + +Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. + +Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. + +4. Redistribution. + +You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: + +1. You must give any other recipients of the Work or Derivative Works a copy of this License; and + +2. You must cause any modified files to carry prominent notices stating that You changed the files; and + +3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and + +4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. + +You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. + +5. Submission of Contributions. + +Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. + +6. Trademarks. + +This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. + +Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. + +In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. + +While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. + diff --git a/apn/lean/docs/loogle/loogle.md b/apn/lean/docs/loogle/loogle.md new file mode 100644 index 00000000..75ff717a --- /dev/null +++ b/apn/lean/docs/loogle/loogle.md @@ -0,0 +1,71 @@ + +# Loogle + +Loogle searches Lean and Mathlib definitions and theorems. + +## Query language + +Loogle finds definitions and lemmas in various ways: + +1. By constant: + `Real.sin` + finds all lemmas whose statement somehow mentions the sine function. + +2. By lemma name substring: + `"differ"` + finds all lemmas that have `"differ"` somewhere in their lemma _name_. + +3. By subexpression: + `_ * (_ ^ _)` + finds all lemmas whose statements somewhere include a product where the second argument is + raised to some power. + + The pattern can also be non-linear, as in + `Real.sqrt ?a * Real.sqrt ?a` + + If the pattern has parameters, they are matched in any order. Both of these will find `List.map`: + `(?a -> ?b) -> List ?a -> List ?b` + `List ?a -> (?a -> ?b) -> List ?b` + +4. By main conclusion: + `|- tsum _ = _ * tsum _` + finds all lemmas where the conclusion (the subexpression to the right of all `→` and `∀`) has the + given shape. + + As before, if the pattern has parameters, they are matched against the hypotheses of + the lemma in any order; for example, + `|- _ < _ → tsum _ < tsum _` + will find `tsum_lt_tsum` even though the hypothesis `f i < g i` is not the last. + +If you pass more than one such search filter, separated by commas, Loogle will return lemmas which match _all_ of them. +The search +`Real.sin, "two", tsum, _ * _, _ ^ _, |- _ < _ → _` +would find all lemmas which mention the constants `Real.sin` and `tsum`, have `"two"` as a +substring of the lemma name, include a product and a power somewhere in the type, *and* have a +hypothesis of the form `_ < _` (if there were any such lemmas). Metavariables (`?a`) are assigned independently in each filter. + +## CLI usage + + $ loogle '(List.replicate (_ + _) _ = _)' + Found 5 declarations mentioning List.replicate, HAdd.hAdd and Eq. + Of these, 3 match your patterns. + + List.replicate_add + List.replicate_succ + List.replicate_succ' + + USAGE: + loogle [OPTIONS] [QUERY] + + OPTIONS: + --help + --interactive, -i read querys from stdin + --json, -j print result in JSON format + --module mod import this module (default: Mathlib) + --path path search for .olean files here (default: the build time path) + --write-index file persists the search index to a file + --read-index file read the search index from a file. This file is blindly trusted! + +By default, it will create an internal index upon starting, which takes a bit. +You can use `--write-index` and `--read-index` to cache that, but it is your +responsibility to pass the right index for the given module and search path. diff --git a/apn/lean/docs/lrslib/LICENSE b/apn/lean/docs/lrslib/LICENSE new file mode 100644 index 00000000..a43ea212 --- /dev/null +++ b/apn/lean/docs/lrslib/LICENSE @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 675 Mass Ave, Cambridge, MA 02139, USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) 19yy + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/apn/lean/docs/lrslib/lrs-userguide.md b/apn/lean/docs/lrslib/lrs-userguide.md new file mode 100644 index 00000000..248ee135 --- /dev/null +++ b/apn/lean/docs/lrslib/lrs-userguide.md @@ -0,0 +1,1065 @@ + + +   + +###   David Avis          avis@cs.mcgill.ca     [http://cgm.cs.mcgill.ca/~avis](http://cgm.cs.mcgill.ca/%7Eavis) + +[What's new](./whatsnew.html) + +[Introduction](#Introduction) + +[lrs: installation and usage](#Installation%20Section) + +[mplrs: installation and usage](#mplrs) + +[lrsnash: installation and usage +](#nash) + +  + +[File formats](#file) + +[Basic options](#Options) + +[Arithmetic packages ](#Arithmetic%20Packages) + +[Estimation](#Estimation) + + + +[Extreme point enumeration and eliminating redundant +inequalities](#redund) [](#fourier) + +[Linear programming](#Linear%20Programming) + +[Fourier elimination](#fourier) + +[(New)Testing redundancy in projections](#hpred) + +[Volume and triangulation](#Volume%20Computation) + +[Voronoi Diagrams and Delaunay Triangulations + +](#Voronoi%20Diagrams) + +[Linearities](#Linearities) + +[Timing, interrupts and restarts +](#timing) + +[(New)Vertex/Facet cross reference listing +](#hvref) + +[Error messages and troubleshooting](#Timing%20and%20Interrupts) + +[Hints and comments](#Hints%20and%20Comments) + +[Acknowledgements and References](#Acknowledgements) + +------------------------------------------------------------------------ + +------------------------------------------------------------------------ + +### Introduction + +A polyhedron can be described by a list of inequalities +(*H-representation)* or as by a list of its vertices and extreme rays +(*V-representation).lrs* is a C program that converts a H-representation +of a polyhedron to its V-representation, and vice versa.  These problems +are known respectively at the *vertex enumeration(VE)* and *convex +hull(CH) problems*. +Fukuda's [FAQ page](https://people.inf.ethz.ch/fukudak/soft/soft.html)   +contains a more detailed introduction to the problem, along with many +useful tips for the new user. + +*lrs* is based on the *reverse search* algorithm developed with Komei +Fukuda, see +[(](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AF92b.ps)[AF](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AF92b.ps)[1992)](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AF92b.ps) +, modified to use lexicographic pivoting  and implemented in rational +arithmetic. It uses limited multithreading via OpenMP.  +[(](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98a.ps)[Av](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98a.ps)[1998a)](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98a.ps) +contains a technical description, and +[(](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98b.ps)[Av](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98b.ps)[1998b)](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98b.ps) +contains some computational experience. +*mplrs* is a full parallel version of *lrs* based on Open MPI for +distributed systems, developed with Skip Jordan, see +[(AJ2015)](http://arxiv.org/abs/1511.06487). + +The input files are in *Polyhedra format* , developed with Fukuda. The +format is essentially self-dual, and the output file produced can be +read in as an input file, with very minor modifications, to perform the +reverse transformation. This format is compatible with that  used in +Fukuda's *[cddlib ](https://www.inf.ethz.ch/personal/fukudak/cdd_home/)* +package, which performs the same transformations using a version of the +*double description method*.  The program +[normaliz](https://www.normaliz.uni-osnabrueck.de/) provides a parallel +version of the double description method. Another program using the same +file format is the primal-dual method +*[pd](http://www.cs.unb.ca/profs/bremner/pd/),* developed by Bremner, +Fukuda and Marzetta .  It is essentially dual to *lrs,* and is very +efficient for computing H-representations of simple polyhedra, and +V-representations of simplicial polyhedra. It will compute the volume of +a polytope given by an H-representation. Links to additional VE/CH +programs are given +[here](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/links.html). + +Polyhedra handled by *lrs * need not be full dimensional  and may +contain input linearities and redundant columns .  *lrs* accepts either +integer or rational input, and produces integer or rational output. All +computations are done exactly using hybrid arithmetic, starting with 64 +bits and moving to 128 bits and extended precision (GMP or built-in) if +necessary, see [(AJ2021)](https://arxiv.org/abs/2101.12425).  Since it +is a pivot based method, *lrs* can be very slow for degenerate inputs: +i.e. H-representations of non-simple polyhedra, and V-representations of +non-simplicial polyhedra. On the other hand, it does not store the +vertices/ rays or facets produced, so for very large problems it may be +the only method that can solve the problem.  Using mplrs, even with just +a few cores, significantly speeds up the computation. A discussion of +various vertex enumeration/convex hull methods and the types of +polyhedra that cause them to behave badly is contained in [(ABS +1997).](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/ABS96a.ps)  A more +recent discussion with extensive empiral tests can be found in +[(AJ2017)](https://arxiv.org/abs/1511.06487).  Considerable technical +assistance over several decades has been provided by David Bremner. + + Functions of *mplrs*/*lrs* include: + +- [V-H transformation](#Installation%20Section): converting an + H-representation to a V-representation and vice versa +- [Estimating](#Estimation) the number of vertices/rays or facets of a + polytope, and estimating the total running time (lrs only) +- [Triangulating and computing the volume](#Volume%20Computation) of a + polytope given by a V-representation +- Removing [redundancy](#redund) from an H or V-representation and + computing a [minimum representation](#redund). Parallel version in + mplrs (v7.3 new) +- [Projecting](#fourier) a polyhedron to a subset of its variables + (Fourier elimination). Parallel version in mplrs (v7.3 new) +- Determining if an inequality is [redundant in computing the + projection](#hpred) to a subset of its variables (uses SMT-solver, + v7.2 new) +- Solving [linear programming](#Linear%20Programming) problems in exact + arithmetic (Simplex method, lrs only) +- Computing the [Voronoi](#Voronoi%20Diagrams) vertices and rays for an + input set of data points and the corresponding [Delaunay + triangulation](#Voronoi%20Diagrams) +- [Eliminating](#eliminate) variables in linearities in + H-representations and [extracting columns](#eliminate) from + V-representations (lrs only) +- Computing all [Nash equilibria](#nash) for 2-person matrix games + (lrsnash) +- Computing a [cross reference table](#hvref) of vertices/rays vs + facets +- The ability to [suspend and restart](#timing) execution at any time + for H-V transformations + +Redundancy removal involves the removal of any inequalities that are not +required to represent the polyhedron in an H-representation. For a +V-representation it is  the problem of evaluating the extreme points and +extreme rays. Finding a minimum representation involves locating any +hidden linearities in the input file. These problems are normally  +considerably easier than the H to V and V to H transforamtions performed +as they are performed by linear programming. In some cases, redundancy +can greatly slow the processing time taken for H-V transformation using +*lrs/mplrs,* and it is advisable to remove any redundancy and hidden +linearities from the input file before starting a long run. + +These programs can be distributed freely under the GNU GENERAL PUBLIC +LICENSE. Please read the file COPYING carefully before using.  Please +inform the authors of any interesting applications for which these +programs were helpful. + +------------------------------------------------------------------------ + +lrslib installation and usage + +Package install is the simplest for linux or WSL/linux users, but may +not contain the latest version of lrslib: + +Debian/Ubuntu (2025.3.25: v7.1):  sudo apt install lrslib     +(maintained by David Bremner \ ) + +Fedora (2025.3.25: v7.3):              sudo dnf install lrslib     +(maintained by Jerry James \ ) + +Additional instructions for installing **mplrs**, a multithreaded +implementation of **lrs** using MPI, are [here](#mplrs). + +Precompiled binaries lrs, lrsgmp for some Linux, Apple and Windows +machines are +[here](https://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/archive/binaries/). +These may be slower for problems requiring very long integers. + +Install from source code: + +- From lrs home page, click on "Download" and retrieve the file + lrslib-073.tar.gz +- Unpack with: +- Go to the new directory +-  make lrs with various arithmetic packages (it may be necessary to + edit makefile to set the path to the gmp library) + +        This produces binaries **lrs** (hybrid arithmetic) and the +usually slower  **lrsgmp** (GMP arithmetic) + +         For compilers without \_\_int128 and/or OpenMP support you will +need to edit the makefile as indicated at the beginning of that file. + + +- You will need to have write permission to /tmp to run the hybrid + arithmetic programs lrs. Temporary files are normally removed before + termination. + +- If  you do not have GNU MP installed you can try using the built in + lrs [arithmetic package](#Arithmetic%20Packages): +- Test the program  + +This is a list of the 8 vertices with each co-ordinate +/- 1.  The +\*\*\*\*\* should be replaced by the actual number, 8, of vertices. +Since *lrs* does not save the output produced, it does not know this +value until the execution terminates. This output is now essentially the +same as file cube.ext. To complete the test type: + +Now the output produced is essentially the file cube.ine, with the +inequalities appearing in a different order. + + +Binaries produced by % make lrs or % make lrsgmp + +            **lrs**                 hybrid [arithmetic +package](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/USERGUIDE63.html#Arithmetic%20Packages) +starting with  64 bit arithmetic, then 128 bit, then GMP. +            **lrsgmp**        GMP arithmetic only +            +          + +Additional instructions for installing **mplrs**, a multithreaded +implementation of **lrs** using MPI, are [here](#mplrs). + +###  File formats + +  + +**Note for cdd users**: *lrs* uses essentially the same file format as +*cdd*. Files prepared for *cdd* should work with little or no +modification. Note that  the V-representation corresponds to the "hull" +option in *cdd*. Options specific to *cdd* can be left in the input +files and will be ignored by *lrs*.  Note the input files for *lrs* are +read in free format, after the line **m n rational** *lrs* will look for +exactly m\*n rationals or integers separated by white space (blank,  +carriage return, tab etc.). *lrs* will not "drop" extra columns of input +if n is less than the number of columns supplied. + +------------------------------------------------------------------------ + +### Basic options    Also see:     [Online manual](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/man) + +**allbases** + +**bound  x                           **         // Use with +H-representation  - for lrs or nash // + +Either the maximize or minimize option should be selected. x is an +integer or rational. +For maximization (resp. minimization) the reverse search tree is +truncated  whenever the current objective value is less (resp. more) +than x . + + +**cache n** + +**debug  startingbasis endingbasis** + +> Print out cryptic but detailed trace, dictionaries etc. starting at +> \#B=startingbasis and ending at \#B=endingbasis. **debug 0 0** gives a +> complete trace. + +**digits n    **            // placed before the begin statement// + +**dualperturb +** + +If lrs is executed with the maximize or minimize option, the reverse +search tree is rooted at an optimum vertex for this function. +If there are mulitiple optimum vertices, the output will often not be +complete. This option gives a small perturbation to the objective to +avoid this. +A warning message is given if the starting dictionary is dual +degenerate**.** + + +**eliminate** **k   i₁ i₂ ... +i_(k) **   **                                              new in v7.2 +** + +   (H-representation) Eliminates k variables in an H-representation +corresponding to cols **i₁ i₂ i ... i_(k )** by projection onto the +  remaining variables using the Fourier-Motzkin method.  Variables are +eliminated in the order given and redundancy is removed +  after each iteration. +  (V-representation) Delete the k given columns from the input matrix +and remove redundancies (cf. extract where redundancies +  are not removed). +  Column indices are between 1 and n-1 and column zero cannot be +eliminated.  The output is a valid lrs input file.  +  See [Fourier +elimination](file:///C:/Users/avis/Desktop/User%27s%20Guide%20for%20lrs.html#fourier), +also **project** and **extract + +** +**estimates k**     Estimate the output size. Used in conjunction with +maxdepth - see +[Estimation.](file:///C:/Users/avis/Desktop/User%27s%20Guide%20for%20lrs.html#Estimation) + +  + +**extract k   i₁ i₂ ... i_(k          )** (lrs only)  v7.2** +      ** (H-representation) A preprocessing step to remove linearities +(if any) in an H-representation and resize the A matrix.  The +       output as a valid lrs input file. The resulting file will not +contain any equations but may not be full dimensional as there +       may be additional linearities in the remaining inequalities. +Options in the input file are stripped.  The user can specify +       the **k** columns  **i₁ i₂ ... i_(k)** to retain otherwise if k=0 +the columns are considered in the order 1,2,..n-1.  Linear dependent +       columns are skipped and additional indices are taken from +1,2,...,n-1 as necessary.  If there are no linearities in the input +       file the given columns are retained and the other ones are +deleted. +       (V-representation) Extract the given columns from the input file +outputing a valid lrs input file.  Options are stripped.** +      ** (See also **eliminate** and **project**)** + +geometric  **               // H-representation  or voronoi option only +// + +          For more information and an example see Geometric Rays in +[Hints and Comments](#Hints%20and%20Comments) . + +**incidence** +           This option automatically switches on **printcobasis** , so +see below for a description of this option first. + +> Can be used with printcobasis n. (Ver 4.2b) +> +> For input H-representation, indices of all input inequalities that +> contain the vertex/ray that is about to be output. For a simplicial +> face, there is no new output, since these indices are already listed. +> Otherwise, the additional tight inequalities are listed after a colon. +> Eg: +> **V#1 R#0 B#1 h=0 facets  12 14 15 16 : 9 10 11 13 I#8 det= 8** +> ** 1  0  0  0  1** +> The vertex **0 0 0 1** satisfies 8 input inequalities as equations, as +> indicated by **I#8** : those with indices **12,14,15,16** are in the +> cobasis, and those with indices **9, 10, 11, 13** are in the basis. +> For a ray: +> **V#1 R#5 B#1 h=0 facets  5 9\* 10 11 12 13 : 2 3 4 I#8 det= 8** +> ** 0  1  1  0  0  1  1** +> Here the ray **1  1  0  0  1  1** lies on 8 inequalities, with indices +> **5 10 11 12 13** in basis and **2 3 4 i**n cobasis. The starred index +> **9\*** indicates that the ray is terminated by the input inequality +> 9. This inequality is in the cobasis and defines the vertex from which +> the ray starts. +> +> For input V-representation, indices of all input vertices/rays that +> lie on the facet that is about to be output: +> **F#5 B#3 h=2 vertices/rays  7 8\* 11 13 15 : 1 3 5 9 I#8 det= 16** +> **1 -1  0  0  0** +> The facet generated by inequality x₁ \<= 1 contains 8 input vertices, +> as indicated by I#8: those with indices **7,11,13,15** are in the +> cobasis, and those with indices **1 3 5 9** are in the basis.The +> starred index **8\*** indicates that this vertex  is also in the +> cobasis, but is not contained in the facet. It arises due to the +> lifting operation used with input V-representations. + +**\#incidence** + +> The same as printcobasis. Included for compatability with *cdd.* + +**linearity  k  i₁ i₂ i ... i_(k)** + +> The input contains k linearities in rows **i₁ i₂ i ... i_(k)** of the +> input file are equations. See [Linearities.](#Linearities) + +**maxdepth k** + +**maximize ** **a₀ a₁ ... +a_(n-1)** **                                          ** // +H-representation  only // +**minimize  ** **a₀ a₁ ... +a_(n-1)**                                           // H-representation  +only // + +If used with lrs the starting vertex maximizes (or minimizes) the +function  a₀ + a₁ x ₁ + ... + a_(n-1) x_(n-1). +The dualperturb option may be needed to avoid dual degeneracy. +See Nash Equilibria and  [Linear Programming](#Linear%20Programming) + +**maxcobases n        ** //from Version 6.0 // +       After n cobases have been generated lrs terminates and returns +restart data for all unexplored roots of subtrees (except for leaves +which are output). These subtrees are the unexplored siblings on the +path back to the root of the reverse search tree. Used by +[mplrs](#mplrs) to break up large subtrees into smaller pieces. +** +maxincidence n  k         //from v.7.3// +      ** Prunes the search tree when the depth is at least k and the +current vertex/facet has incidence at least n.  +       Using **verbose** a message is printed whenever the search tree +is pruned.** + +maxoutput n**    +       Limits number of output lines produced (either vertices+rays or +facets) to n +** +mindepth k** + +**nonnegative                     ** // This option must come before the +begin statement// +                                                                                            +//H-representation only // +           Bug: Can only be used if the origin is a vertex of the +polyhedron  + +> For problems where the input is an H-representation of the form +> b+Ax\>=0, x\>=0 (ie. all variables non-negative, all constraints +> inequalities) it is not necessary to give the non-negative constraints +> explicitly if the nonnegative option is used. This option cannot be +> used for V-representations, or with the linearity option (in which +> case the linearities will be treated as inequalities). This option may +> be used with redund , but the implied nonnegativity constraints are +> not tested themselves for redundancy. To test everything it is +> necessary to enter the nonnegativity constraints explicitly in the +> input file. (In Ver 4.1, the origin must be a vertex). + +**printcobasis  k                                 ** + +**printslack              **          // Use with H-representation // + + +lrs prints a list of the indices of the input inequalities that are +satisfied strictly for the current vertex, ie. corresponding slack +variable is positive. +If nonnegative is set, the list will also include indices n+i for each +decision variable x_(i) which is positive. + + + +**project** ****k   i₁ i₂ ... +i_(k)**                                                  new in v7.2 +** + +       (H-representation) Project the polyhedron onto the **k** +variables corresponding to cols **i₁ i₂ ... i_(k)** using the +Fourier-Motzkin +       method. Column  indices are between 1 and n-1 and column zero is +automatically retained.  Variables not contained in the list +       are eliminated using a heuristic which chooses the column which +minimizes the product of the number of positive and negative +       entries.  Redundancy is removed after each iteration using linear +programming. +       (V-representation) Extract the k given columns from the input +matrix and remove redundancies. Column  indices are between 1 +       and n-1 and column zero is automatically extracted (cf. extract +where redundancies are not removed). +       The output as a valid lrs input file.  See [Fourier +elimination](#fourier), also **eliminate** and **extract** + + +** +** +****redund start end                      new in v7.1 +          **** Check input line numbers from **start** to **end** and +remove any redundant lines. +            **redund 0 0**  will check all input lines.  See +[redund](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/USERGUIDE71.html#redund)** + +redund_list k   i₁ i₂ ... i_(k                 )** ****new in v7.1**** + +Check the **k** input line numbers with indices **i₁ i₂ ... i_(k)**  +from and remove any redundant lines. See [redund](#redund) + + +**restart  V# R# B# depth {facet \#s or vertex/ray \#s**}  +**\[integervertices n**\]                                               +                    /\* new in V 7.0 \*/              + +  + +****startingcobasis i₁ i₂ i ... i_(n-1)** +** + +******testlin      (before the begin line only)   H-representation +only**  (new 7.3)**** **** +**   ** + +**threads  n**     (new in 7.3) lrs only + +**truncate                                           ** // +H-representation only //       + +> The reverse search tree is truncated(pruned)  whenever a new vertex is +> encountered. Note: This does note necessarily produce the set of all +> vertices adjacent to the optimum vertex in the polyhedron, but just a +> subset of them. See +> [here](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/lexpos.html) for a +> description of how to use this option. + +**verbose** + +> Print slightly more detailed information about the run. + +**volume                                             ** // +V-representation  only // + +**voronoi                                             ** // +V-representation  only - place immediately after end statement // + +------------------------------------------------------------------------ + +###   Linear Programming              + +**lponly** + +             and one of the options maximize or minize: + +**maximize a₀ a₁ ... a_(n-1)**                                           +// H-representation  only // + +**minimize a₀ a₁ ... +a_(n-1)**                                             // +H-representation  only // + +To print the dictionary at a few key points also include the option: + +**verbose +** + +**New in V4.2.** Dual variables are now printed at termination. If the +linearity option is used, only a partial list of dual variables will be +given. +                       Dual variable y_(i) refers to inequality number i +in the input. + +------------------------------------------------------------------------ + +### Volume and triangulation + +*lrs* can be used to compute the volume of a full dimensional polytope +given as a V-representation. This follows from the fact that lex-postive +bases form a triangulation of the facets, and that a V-representation is +always lifted. See "Theoretical Description" on lrs home page for some +remarks on this. The option + +**volume    ** +                                                                        +// V-representation only // + +will cause the volume to be computed. For input cube.ext, the output +is: +**\*Volume=8** + +The triangulation can be output by adding also the option verbose. +This would give the output: + +F#0 B#1 h=0 vertices/rays  4 6 7 8 I#8 det= 8 + 1  1  0  0 + 1  0  1  0 + 1  0  0  1 +F#3 B#2 h=1 vertices/rays  4 5 6 7 I#8 det= 8 +F#3 B#3 h=2 vertices/rays  3 4 5 7 I#8 det= 8 + 1 -1  0  0 +F#4 B#4 h=3 vertices/rays  2 3 4 5 I#8 det= 8 + 1  0  0 -1 +F#5 B#5 h=4 vertices/rays  1 2 3 5 I#8 det= 8 +F#5 B#6 h=2 vertices/rays  2 4 5 6 I#8 det= 8 + 1  0 -1  0 +end +\*Sum of det(B)= 48 +\*Volume= 8 + +Each of the 6 bases corresponds to a simplex. +The first simplex is composed of vertices 4 6 7 8, second simplex is 4 5 +6 7, etc. + +If the **volume** option is applied to an H-representation, the results +are not predictable. If the option is applied to a V-representation of + a polytope that is not full dimensional, the volume of a projected +polytope is computed. The projection used is to the lexicographically +smallest coordinate subspace, see [Avis, Fukuda, Picozzi +(2002)](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AFP02a.ps).  + +For polytopes given by a H-representation, it will first be necessary to +compute the V-representation. + +------------------------------------------------------------------------ + +### Voronoi diagrams and Delaunay triangulations + +*lrs* can be used the compute the V-vertices of a Voronoi diagram of a +set of data points in n-1 dimensional space. To do this we use a +standard lifting procedure (see, e.g., Edelsbrunner, "Algorithms in +Combinatorial Geometry," pp 296-297) . Each point is mapped to a half +space tangent to the parabaloid in n dimensions, by the mapping: + +p₁  , p₂  , ...., p _(n-1)     -\>    (p₁ ²  +   p₂² +  ...   +  +p_(n-1)²  ) - 2 p₁  x ₁  - 2 p₂  x₂ - .... - 2  p _(n-1) x_(n -1 ) + x +_(n)\>= 0 + +*lrs* is applied to the H-representation so created.  This +transformation is performed automatically for a V-representation if the + +**voronoi         ** // V-representation only - place immediately after +end statement // + +option is specified. +**Note**: The input file must consist entirely of data points (no rays), +i.e.. there must be a one in column one of each line. The **volume** +option should not be used, since the volume reported will not be the +volume of the original V-representation. +The output will consist of the Voronoi vertices (columns beginning with +a one) and Voronoi rays (columns beginning with zero) for the Voronoi +diagram defined on the data points.  If the **printcobasis** option is +given, the n "**data points**" indices produced will tell which set of +input data points corresponds to the given Voronoi vertex or ray. In +case of degeneracies, a given Voronoi vertex may be generated by more +than n of the input data points. In this case, use of the **allbases** +option will cause all  sets of n input data points corresponding to a +Voronoi vertex to be printed. Each cobasis will define a **Delaunay +triangle** in the dual. For Voronoi rays, the immediately preceding  +cobasis is the cobasis of the the Voronoi vertex from which the ray +emanates.  The index followed by a **\*** is the data point to drop in +order to generate the ray. If the **geometric** option is given the +correspondence between Voronoi rays and Voronoi vertices will be +produced automatically. + +**Example:** Compute the Voronoi diagram and Delaunay triangulation of +the planar point set (0,0), (2,1), (1,2), (0,4), (4,0), (4,4) (2,-4). + +[TABLE] + + + + + +[TABLE] + +Visualizations made using [GeoGebra](https://www.geogebra.org). + +###   redund: extreme point enumeration and eliminating redundant inequalities     (new options parallel version from v7.1) + +###   minrep: finding a minimum representation of an H- or V-representation      (new options parallel version from v7.3) + +A convex hull problem that occurs frequently is to enumerate the extreme +points (vertices) of a given set of input points. This problem is in +fact much simpler than the problem of finding the facets of the given +input point set. It can be solved by linear programming.  The dual +problem is to remove redundant inequalities from an H-representation. An +input  inequality is redundant if it can be deleted without changing the +polyhedron. It is strongly redundant if it is not satisfied as strict +inequality by any feasible point. A vertex/ray in a V-representation is +strongly redundant if it is strictly interior to the convex hull. + +An H-representation may contain "hidden linearities" or inequalities +that are always satisfied as equations. A similar situation occurs in a +V-representation where the convex hull contains a line. The minimum +representation problem is to identify all linearities in an input file, +output them explicity using the linearity option, and then remove any +remaining redundant rows. The dimension of the input set is output at +the end of the computation. + +Redundancy removal can be obtained by using the lrs clone redund or by +lrs via the redund/redund_list options described above. + +A minimum representation can be obtained by using the lrs clone minrep +or by lrs via the testlin (before the begin line) and redund/redund_list +options. +mplrs can compute a minimum representation in parallel by use of the +-minrep command line argument. Due to technical issues in the +parallelization mplrs does not do redundancy removal without also +computing a minimum representation. + +The ouput will be streamed if the verbose option is included after the +end line. +On each line \*nr indicates non-redundant, \*re indicates redundant, +\*sr indicates strongly redundant, and \*li indicates linearity. + +**Usage:** +(1) **With options**  (allows partial redundancy checking for large +inputs) + +Add the [redund](#redopt) or [redund_list](#redopt) option after the end +statement of a H- or V-representation. +Execute **% lrs filename**  **or   %mpirun -np \ mplrs +filename** + +If more than one redund/redund_list option is in the input file the last +one read takes priority. + +(2) **Without options**  (complete redundancy check of all input lines, +overidden by redund/redund_list option in input) + +To remove input lines that are not vertices/rays from a V-representation +or redundant inequalities from an H-representation use the command: + +For example, using the file mit.ine from the distribution: + +          % redund mit.ine + +> \*redund:lrslib v.7.1 2020.5.23(64bit,lrslong.h,overflow checking) +> +> \*Input taken from file mit.ine +> mit.ine +> \*mulint   : max(\|a\|,\|b\|) \> 2147483647 +> +> \*redund2 found - restarting +> \*redund:lrslib v.7.1 2020.5.23(128bit,lrslong.h,overflow checking) +> +> \*Input taken from file mit.ine +> mit.ine +> \*row 75 was redundant and removed +> \*row 77 was redundant and removed +> \*row 89 was redundant and removed +> -------------------------- +> \*row 709 was redundant and removed +> H-representation +> begin +> 708  9  rational +>  36  0  0 -2 -2 -1  0  0  0 +> ---------------------------- +>   +>  0  0  0  0  0  0  0  0  1 +> end +> \*Input had 729 rows and 9 columns: 21 row(s) redundant +> \*Overflow checking on lrslong arithmetic +> \*redund:lrslib v.7.1 2020.5.23(128bit,lrslong.h) + +From this output we first see that redund tried 64 bit arithmetic but +detected an overflow and reran with 128 bit arithmetic. +It found 21 redundant rows which were removed from the file. +The resulting output file can be used directly with lrs. +In fact, lrs works best if the input is non-redundant, see the section +[Redundancy vs Degeneracy.](#Hints%20and%20Comments) + +------------------------------------------------------------------------ + +### Linearities    + + +**linearity  k  i₁ i₂ i ... i_(k)** + +> The input file contains k linearities. If the input is a +> H-representation, the rows **i₁ i₂ i ... i_(k)** of the input file are +> equations. For a V-representation, the rows with these indices should +> begin with zero in column one, and will be interpreted as lines rather +> than rays.  Linearities defined on the input vertices of a +> V-representation are not defined, but the program will accept them and +> produce some output. Each of the indice **i_(k)** must be a distinct +> number between **1** and **m**. With an  H-representation, linearities +> are useful for enumeration of vertices on a facet or lower dimensional +> subspace. For example the file: +> +> **cube_ridge** +> **\*cube of side 2 centred at the origin** +> **H-representation** +> **linearity 2  1 5** +> **begin** +> **6 4 rational** +> **1 1 0 0** +> **1 0 1 0** +> **1 0 0 1** +> **1 -1 0 0** +> **1 0 -1 0** +> **1 0 0 -1** +> **end** +> +> causes vertices to be enumerated on the ridge which is the +> intersection of the two facets +> +> x₁ = -1   and   x₂ = 1 +> +> so the output is the pair of vertices +> +> cube_ridge +> \*Input linearity in row(s) 1 5 +> V-representation +> begin +> 2  4  rational +>  1 -1  1  1 +>  1 -1  1 -1 +> end +> +> Specifying linearities in this way will often produce +> [redundancy](#Hints%20and%20Comments) , especially if the dimension of +> the problem is reduced considerably. As a preprocessing step, it is +> useful to apply to remove any redundancy by [*redund*](#redund). In +> the case of the above problem the output produced by *redund* is: +> +> cube +> \*Input linearity in row(s) 1 5 +> \*row 2 was redundant and removed +> \*row 4 was redundant and removed +> H-representation +> linearity 2 1 2 +> begin +> 4 4 rational +>  1  1  0  0 +>  1  0 -1  0 +>  1  0  0  1 +>  1  0  0 -1 +> +> and two redundant halfspaces were removed. +> +> Redundant columns are closely related to linearities. If we examine +> the V-representation of cube_ridge above we can see that it is just a +> line segment in 3 dimensional space. Further,  columns 2 and 3 are +> multiples of column 1. If lrs is applied to this file, the column +> redundancies give rise to two linearities, so the output will appear +> as the H-representation given above: geometrically the intersection of +> two planes (the linearities) with two half-planes (defining the +> endpoints of the line segment). +> +> In general, the representation of the linearity space is not unique, +> however the one produced by lrs should be the same as that produced by +> cdd. + + + +------------------------------------------------------------------------ + +### Error messages and troubleshooting + +The most common error occurs from an incorrect input file specification, +please check the section [File Formats](#file) carefully. In particular, +*lrs* does not check the type or number of input coefficients +specified.  After the line +**m n rational** +you must specify **exactly** m\*n rational or integer coefficients. They +are read  in **free format** , but normally each input facet or +vertex/ray is begun on a new line.  See [note for cdd +users.](#Note%20for%20cdd%20users) + +The following error messages are produced by *lrs* . They are  arranged +in alphabetic order. + +**Cannot find linearity in the basis +** + +> The linearity option was specified but a basis cannot be created. +> Check the linearity indices are all less than n-1 and are disitinct. + +**Data type must be integer of rational** + +**Digits must be at most 2295  Change MAX_DIGITS and recompile     (This +message does not appear if the default gmp arithmetic package is used)** + +**Invalid input: check you have entered enough data! +** + +> Usually means that end of file was reached before enough input data +> was read. + +** +Invalid Co-basis - does not have correct rank** + +**Maximize/minimize only valid for H-representation** + +**No begin line** + +**No data in file** + +**No feasible solution** + +**Starting cobasis indices must be distinct and in range 1 .. m** + +**Trying to restart from infeasible dictionary** + +**mplrs error messages** +** +Error: lponly option not supported - use lrs!** + +**The following message may be produced when building lrs on macOS** + +**OpenMP support not found, disabling OpenMP parallel build +** + + + + +------------------------------------------------------------------------ + +Hints and comments + +#### H- vs V- representation + + *lrs* is programmed to manipulate H-representations directly. A file +presented as a V-representation is processed by lifting it to a cone in +one higher dimension, which is treated internally as a H-representation. +If the input file is a polytope which contains the origin, then the user +has two options. Submit it as a V-representation and have it processed +as just described, or submit it as a H-representation, and interpret the +output as a list of facet inequalities rather than "vertices". Since +this will not be lifted, it will be processed in a different way by +*lrs*. Sometimes a degenerate V-representation may run more quickly as a +H-representation, and sometimes more slowly. To decide which +representation to use for a large problem, the user can run the +**estimates** option and choose the representation with fewest estimated +bases. +  + +#### Redundancy vs Degeneracy + +For an H-representation, an input is redundant if some inequality can be +deleted without changing the polyhedron. It is degenerate if (in d +dimensions) at least one vertex lies on d+1 or more facets.  Similarly +in a V-representation an input is redundant if some input point is not a +vertex of the convex hull.  It is degenerate if some facet contains d+1 +or more input points. The [options](#Options)   **printcobasis** and +**incidence** give degeneracy information. Degeneracy causes pivot  or +triangulation based methods such as *lrs* to  run slowly. Redundancy is +one cause of degeneracy, but it can be avoided by pre-processing the +input files. See section [redund: extreme Point Enumeration and +Redundant Inequalities](#redund) for instructions on how to do this. +This pre-processing is unnecessary if it is known that the input is +non-redundant. + +Even with redundant input removed a polyhedron may be highly degenerate. +In distribution directory ine/metric there are many highly degenerate +combinatorial polytopes. These are difficult problems for all vertex +enumeration/convex hull programs that use pivoting, such as *lrs*.  For +example, the file *cp6.ine* is a polytope with 368 facets in  16 +dimensions. It has 32 vertices, but computing these required the +evaluation of 4,844,923,002 bases!(see [Avis-Jordan, +2017](https://arxiv.org/abs/1511.06487)) + +#### Memory considerations + +The strong point of *lrs* is that it does not save the output produced, +so in theory it cannot run out of memory.  With cache size one all +memory is allocated at the beginning, so if *lrs* starts running it will +not run out of memory. It is possible however that the number of digits +required to do the calculations exceeds the amount specified on the +**digits** option, or the default. In practice, this problem will also +arise early in the computation. In any case, a message is printed and +the calculation can be restarted. In order to improve performance, some +dictionaries should be cached. The default of 10 can be overridden by +the **cache**option. If the dictionary is in the cache it does not need +to be recomputed when backtracking, reducing  processing time by about +40%. Since the cache is allocated dynamically, a cache size that is too +large can potentially use up large ammounts of machine memory. + +#### Geometric Rays + +A minimum V-representation of a polyhedron is a minimum set of vertices +and rays such that each point in the polyhedron can be expressed as a +convex combination of vertices plus a non-negative combination of rays. +For the cube, if we delete the inequality +x₃ \<= 1, i.e.. the line 1 0 0 -1 from file *cube.ine*, we get the +output: +**V-representation** +**\*\*\*\*\* 4 rational** +**1 1 1 -1** +**0 0 0 1** +**1 -1 1 -1** +**1 1 -1 -1** +**1 -1 -1 -1** +**end** +indicating the polyhedron is the convex combination of 4 vertices and 1 +ray. With the **geometric** option, we get the output: +**V-representation** +**begin** +**\*\*\*\*\* 4 rational** +**1 1 1 -1** +**0 0 0 1  \* 1 1 1 -1** +**1 -1 1 -1** +**0 0 0 1  \* 1 -1 1 -1** +**1 1 -1 -1** +**0 0 0 1  \* 1 1 -1 -1** +**1 -1 -1 -1** +**0 0 0 1  \* 1 -1 -1 -1** +**end** +This indicates that geometrically, the polyhedron has 4 parallel extreme +rays (0,0,t) , one incident to each vertex. With the **geometric** +option, all rays will be printed. Without the option, *lrs* tries to +print each ray once, but in some cases duplicates will remain, see  +subsection Output Duplication. + +**Output Duplication** + +For degenerate inputs, pivot based methods for vertex/ray enumeration +such as *lrs* may generate the same output ray many times. An output is +only printed when it occurs with a lexicographically minimum basis. This +removes all duplicate vertices, but rays may still be output more than +once. This is due to the fact that duplicate geometric rays cannot +always be detected without storing the output. Since V-representations +are automatically lifted to a higher dimension, this will not happen for +facet enumeration. Unless the **allbases** option is specified, *lrs* +makes checks in order to remove duplicates.   A warning message is +produced when duplicates may occur in the output. They can be removed +using the program *buffer.c*. Two important types of input never produce +duplicate output: polytopes (i.e. bounded polyhedra) and cones (i.e. +polyhedra where the origin is the only vertex). + +------------------------------------------------------------------------ + +Acknowledgements and References + +I would like to thank many people for helping with this implementation +project. Komei Fukuda encouraged me from the start, collaborated in +designing the file formats, and provided many suggestions for improving +the code. Debugging would have been almost impossible without the use of +his program cdd as a benchmark. David Bremner implemented memory +allocation, cacheing and signals. Ambros Marzetta demonstrated the +importance of cacheing and lrslong is based on his earlier +implementation of this as prs_single.  Jerry Quinn coded the integer +divide routine. Bug reports were provided by many users, for which I +thank them. In particular Gerardo Garbulsky's extensive use of earlier +versions suggested many refinements and Andreas Enge helped debug the +volume computation. Tallman Nkgau contributed fourier. + +D. Avis, lrs: A Revised Implementation of the Reverse Search Vertex +Enumeration Algorithm, +[http://cgm.cs.mcgill.ca/~avis/doc/avis/Av98a.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98a.ps) +   In: Polytopes - Combinatorics and Computation, Ed. G. Kalai and G. +Ziegler, Birkhauser-Verlag (2000) 177-198. + +D. Avis, "Computational Experience with the Reverse Search Vertex +Enumeration Algorithm," Optimization Methods and Software, (1998 (to +appear)). +[http://cgm.cs.mcgill.ca/~avis/doc/avis/Av98b.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98b.ps) + +D. Avis, D. Bremner, and R. Seidel, "How Good are Convex Hull +Algorithms?," Computational Geometry: Theory and Applications, Vol +7,pp.265-301(1997). +[http://cgm.cs.mcgill.ca/~avis/doc/avis/ABS96a.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/ABS96a.ps) + +D. Avis and L. Devroye, "Estimating the Number of Vertices of a +Polyhedron," pp. 179-190 in Snapshots of Computational and Discrete +Geometry, ed. D. Avis and P. Bose, School of Computer Science, McGill +University (1994). +[http://cgm.cs.mcgill.ca/~avis/doc/avis/AD94a.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AD94a.ps) +  In: Information Processing Letters, (2000) V. 73, pp. 137-143. + +D. Avis and K. Fukuda, "A Pivoting Algorithm for Convex Hulls and Vertex +Enumeration of Arrangements and Polyhedra," Discrete and Computational +Geometry, Vol. 8, pp. 295-313 (1992).  +[http://cgm.cs.mcgill.ca/~avis/doc/avis/AF92b.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AF92b.ps) + +D. Avis, K. Fukuda and S. Picozzi, "On Canonical Representations of +Convex Polyhedra", Mathematical Software,  ICMS 2002, Ed. A. Cohen, X-S +Gao, N. Takayama, World Scientific, pp.350-360 (2002)  + [http://cgm.cs.mcgill.ca/~avis/doc/avis/AFP02a.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AFP02a.ps) + +D. Avis, G. Rosenberg, R. Savani, B. von Stengel, "Enumeration of Nash +Equilibria for Two-Player Games", Economic Theory 42(2009) 9-37  +[pdf](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/ARSS09a.pdf) + +D. Bremner, K. Fukuda and A. Marzetta, Primal-Dual Methods for Vertex +and Facet Enumeration, 13th ACM  Symposium on Computational Geometry SCG +1997, 49-56.   + + + + + + diff --git a/apn/lean/docs/msolve/LICENSE b/apn/lean/docs/msolve/LICENSE new file mode 100644 index 00000000..d159169d --- /dev/null +++ b/apn/lean/docs/msolve/LICENSE @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/apn/lean/docs/msolve/msolve-tutorial.txt b/apn/lean/docs/msolve/msolve-tutorial.txt new file mode 100644 index 00000000..c182bfcd --- /dev/null +++ b/apn/lean/docs/msolve/msolve-tutorial.txt @@ -0,0 +1,742 @@ + + +1 Introduction +msolve is a C library for solving multivariate polynomial systems of equations. It relies on +computer algebra, a.k.a. symbolic computation, algorithms to compute algebraic representations +of the solution set from which, much, if not all, information can be extracted. + + + + Solving polynomial systems with msolve is global by contrast to local numerical routines. +The use of computer algebra methods allow also the user to bypass classical numerical issues +encountered by numerical methods for polynomial system solving such as those based on +numerical homotopy continuation or semi-definite programming. + msolve relies mainly on Gröbner bases algorithms (see below for a some basic definitions +and properties). It is highly optimized, uses AVX2 vectorization instructions and multi-threading. + It uses the GMP library (handling multi-precision integers) and the FLINT library (handling +arithmetics of univariate polynomials). + msolve can be downloaded from + + https://msolve.lip6.fr + +where binaries (for x86 processors running Linux operating systems) and source files are +provided. + msolve is designed for 64 bit architectures, with AVX2 instructions. + msolve allows you to: + + • isolate all real solutions to polynomial systems with rational coefficients and finitely + many complex solutions; + + • compute Gröbner bases of polynomial systems with coefficients which are either rational + numbers or in a prime field ℤ/𝑝ℤ with 𝑝 < 231 ; + + • compute parametrizations of the solutions of polynomial systems with coefficients which + are either rational numbers or in a prime field ℤ/𝑝ℤ with 𝑝 < 231 (assuming that the + system has finitely many solutions with coordinates in an algebraic closure of the field + generated by the input coefficients). + + msolve is based on Gröbner bases computations. When launching msolve on an input +polynomial system (see the file format in section 2), a Gröbner basis computation starts and +allows msolve to determine if the number of solutions to the system is infinite or finite in an +algebraic closure of the base field (the complex numbers when the input coefficients are rational +numbers). + When the number of solutions is finite, one says that the system (or the ideal generated +by the input equations) has dimension zero at most. Else it has positive dimension. Section 3 +shows how msolve behaves when the input system has positive dimension or when there is +no solution at all in an algebraic closure of the base field (over the complex numbers when the +input coefficients are rational numbers). + When the system has dimension at most zero, msolve can compute the real solutions or, +as said above, compute a Gröbner basis (when the base field is a prime field) or compute a +parametrization of the solutions. Section 4 shows how to use msolve for solving polynomial +systems over the reals when they have dimension at most zero. Section 5 shows how to +use msolve for computing Gröbner bases over prime fields (with some restriction on the + + + + +bit size of the considered prime). Section 6 shows how to use msolve for computing rational +parametrizations of solutions to polynomial systems which have dimension at most zero. Finally, +section 8 summarizes some options which can be used rational parametrizations of solutions to +polynomial systems which have dimension at most zero. Finally, section 8 summarizes some +options which can be used. + The msolve library is described in [1] with implementation details on the algorithms used +therein. All computations performed over the rational numbers (e.g. for computing real roots) are +based on multi-modular computations with a probabilistic stopping criterion. Unless explicitly +requested by the user (see the -l flag in section 8), all computations of Gröbner bases in prime +fields use deterministic algorithms. Change of order algorithms which are used are deterministic +when the input ideal is radical. + + +2 Input file format +msolve allows you to solve polynomial systems either with coefficients which are either rational +numbers or in a prime field ℤ/𝑝ℤ with 𝑝 < 231 . If you aim at solving polynomial systems with +coefficients which are floating point numbers, you can just replace these floating point numbers +with rational numbers. Further, we explain how the input files of msolve should be. + Consider the following polynomial system of equations + 𝑥 + 2𝑦 + 2𝑧 − 1 = 0 + 𝑥 2 + 2𝑦 2 + 2𝑧 2 − 𝑥 + = 0 + 2𝑥𝑦 + 2𝑦𝑧 − 𝑦 = 0 +in ℚ[𝑥, 𝑦, 𝑧]. + In order to solve it with msolve one simply produces a file with the following content + + x,y,z + 0 + x+2*y+2*z-1, + x^2+2*y^2+2*z^2-x, + 2*x*y+2*y*z-y + + + Hence the structure of input files to msolve is as follows: + + 1. the first line contains the variables of the input system, separated with a comma (no + comma at end of line); + + 2. the second line contains the characteristic of the field over which computations are + performed; + + 3. the next lines contain polynomials, in expanded form, separated by a comma and with a + line break (no comma or line break for the last one). + + + + + In each given polynomial, msolve expects a single occurrence of each monomial; if some +monomial appears several times (e.g. as in x+2*y+2*z-x), the behavior of msolve’s parser is +undefined. + When one wants to solve this system over 65521ℤ ℤ + one just replaces 0 by 65521 in the second +line. Note that in the positive characteristic case the coefficients used should be smaller or equal +to 231 − 1. + + x,y,z + 65521 + x+2*y+2*z-1, + x^2+2*y^2+2*z^2-x, + 2*x*y+2*y*z-y + + + + +3 Computing the dimension +To make things explicit on the behavior of msolve when the input system does not have finitely +many complex solutions, let us consider first the example below. + + x, y + 0 + x*y-1, + x + + + Then, msolve outputs + + + [-1]: + + + + indicating that the dimension of the set of complex solutions is −1, hence it is empty. + If now, one considers the following example. + + x, y, z + 0 + x^2-y^2, + x-y + + + Then, msolve outputs + + + + + [1, 3, -1, []]: + + + + The first integer 1 indicates that the complex solution is positive dimensional (note that the +actual dimension of the complex solution set is 2). + + +4 Solving over the reals (finitely many solutions) +The basic functionality msolve allows you to perform is real root isolation for polynomial sys- +tems with rational coefficients and with finitely many complex solutions. This latter requirement +is automatically tested by msolve. + For instance, consider the following input to msolve written in a file in.ms. + + x,y,z + 0 + x+2*y+2*z-1, + x^2+2*y^2+2*z^2-x, + 2*x*y+2*y*z-y + + + Then, typing the following command line + + ./msolve -f in.ms -o out.ms + + + + + will display in the out.ms file the following content. + + [0, [1, + [[[107291359935630315248585097660753910587 / 2^127, 26822839983907578812146274415188477647 / 2^125], [107291359935630315248585097660753910587 / + 2^128, 26822839983907578812146274415188477647 / 2^126], [-355532291286331190123863132844989723573 / 2^131, + -1422129165145324760495452531379958894291 / 2^133]], [[1, 1], [0, 0], [0, 0]], [[38543940173343311950004019810003894311 / 2^127, + 77087880346686623900008039620007788667 / 2^128], [9635985043335827987501004952500973579 / 2^126, 4817992521667913993750502476250486791 + / 2^125], [93053303113782607831679264095876317083 / 2^128, 372213212455130431326717056383505268333 / 2^130]], + [[7089215977519551322153637654828504405 / 2^124, 113427455640312821154458202477256070491 / 2^128], [-1 / 2^127, 1 / 2^127], + [1814839290245005138471331239636097127765 / 2^132, 907419645122502569235665619818048563883 / 2^131]]] + ]]: + + + + + This is a list whose first element is the integer 0 indicating that the input polynomial system +has finitely many complex solutions. The second element of this list is a list which provides the +coordinates of the real solutions as follows: + • the first element is an integer ℓ indicating how many lists are given further; in the above + example, the integer 1 tells that we have a single list (this will be the usual case); + • the next are ℓ lists 𝐿1, . . . , 𝐿ℓ which encode the solutions to the input system; each of them + containing boxes isolating a single real solution. + + + +For instance, from the above output, we deduce that the box defined by + 107291359935630315248585097660753910587 +  +  +  2127 +  107291359935630315248585097660753910587 ⩽ 𝑥 ⩽ 26822839983907578812146274415188477647 + 2125 + , + 26822839983907578812146274415188477647 +  + 2128 + ⩽ 𝑦 ⩽ 2126 + , +  −355532291286331190123863132844989723573 −1422129165145324760495452531379958894291 +  +  +  2131 ⩽ 𝑧 ⩽ 2133 + +contains a single real solution to the input system. + Sometimes, it makes sense to increase the precision. To do that, we use the -p flag, followed +by an integer monitoring the used precision, as follows. + + ./msolve -p 256 -f in.ms -o out.ms + + + + + We obtain in out.ms the following + + [0, [1, + [[[36509357909062631536129668436573070012487487067100583303001175658946635606055 / 2^255, + 4563669738632828942016208554571633751560935883387572912875146957368329450757 / 2^252], + [36509357909062631536129668436573070012487487067100583303001175658946635606055 / 2^256, + 4563669738632828942016208554571633751560935883387572912875146957368329450757 / 2^253], + [-60490684797868661441895377475208744393359927205523538345094237255746825568573 / 2^258, + -483925478382949291535163019801669955146879417644188306760753898045974604548583 / 2^261]], [[1, 1], [0, 0], [0, 0]], + [[3278955798161077339921616998930436909728483733114914607048732943254033559905 / 2^253, + 26231646385288618719372935991443495277827869864919316856389863546032268479285 / 2^256], + [6557911596322154679843233997860873819456967466229829214097465886508067119813 / 2^255, + 13115823192644309359686467995721747638913934932459658428194931773016134239637 / 2^256], + [63328796466738957984825113025800917297614244935801930326677856915848592681411 / 2^257, + 126657592933477915969650226051601834595228489871603860653355713831697185362823 / 2^258]], + [[2412335192444087404657728854347664746943124680534178417488699666831523534165 / 2^252, + 38597363079105398474523661669562635951089994888546854679819194669304376546651 / 2^256], [-1 / 2^255, 1 / 2^255], + [617557809265686375592378586713002175217439918216749674877107114708870024746325 / 2^260, + 308778904632843187796189293356501087608719959108374837438553557354435012373163 / 2^259]]] + ]]: + + + + +5 Computing Gröbner bases +msolve relies on Gröbner bases algorithms which allow one to rewrite the input polynomial +system as an equivalent system which reveals properties of the solution set (dimension, degree) +and to compute “modulo” the input equations. + msolve provides Gröbner bases computations for the so-called grevlex ordering (see e.g. [2]) +when the coefficients either lie in the field of rational numbers or when they lie in the prime +field case. For instance, assume the file in.ms contains the following: + + z1, z2, z3 + 1073741827 + 7*z1*z2+5*z2*z3+z3^2+z1+5*z3+10, + 7*z3^2-27*z1^2-15*z2^2+59*z3+3*z1, + 8*z1^2+13*z1*z3+10*z3^2+z2+z1 + + + + + Now, typing the following command: + + ./msolve -g 2 -f in.ms -o out.ms + + + + + where the -g flag indicates that one aims at computing a Gröbner basis. The value 2 tells +msolve to compute the Gröbner basis for the grevlex order with 𝑧 1 ≻ 𝑧 2 ≻ 𝑧 3 . The computed +Gröbner basis is then printed in the file out.ms as follows. + + #Reduced Groebner basis data + #--- + #field characteristic: 1073741827 + #variable order: z1, z2, z3 + #monomial order: graded reverse lexicographical + #length of basis: 6 elements sorted by increasing leading monomials + #--- + [1*z2^2+832149913*z1^1*z3^1+876889156*z3^2+295279002*z1^1+724775733*z2^1+143165573*z3^1, + 1*z1^1*z2^1+613566759*z2^1*z3^1+766958448*z3^2+766958448*z1^1+613566759*z3^1+153391691, + 1*z1^2+134217730*z1^1*z3^1+268435458*z3^2+671088642*z1^1+671088642*z2^1, + 1*z2^1*z3^2+722232944*z3^3+180778379*z1^1*z3^1+1027531442*z2^1*z3^1+173735741*z3^2+936498976*z1^1+702034498*z2^1+921316952*z3^1+59915395, + 1*z1^1*z3^2+557357968*z3^3+911535897*z1^1*z3^1+419648179*z2^1*z3^1+96648475*z3^2+698659259*z1^1+282295066*z2^1+885328953*z3^1+769127629, + 1*z3^4+250491376*z3^3+716275774*z1^1*z3^1+91652836*z2^1*z3^1+88303466*z3^2+855797860*z1^1+18642214*z2^1+728901227*z3^1+969918485]: + + + + + When one is interested only in the leading monomials of the Gröbner basis (which is a way +smaller output), one simply uses the -g 1 flag as follows + + ./msolve -g 1 -f in.ms -o out.ms + + + + + and we obtain: + + #Leading ideal data + #--- + #field characteristic: 1073741827 + #variable order: z1, z2, z3 + #monomial order: graded reverse lexicographical + #length of basis: 6 elements sorted by increasing leading monomials + #--- + [z2^2, + z1^1*z2^1, + z1^2, + z2^1*z3^2, + z1^1*z3^2, + z3^4]: + + + + + Note that from this list of monomials, one can deduce the Hilbert series of the ideal generated +by the input equations and then its dimension and its degree (see [2]). + Note that when the -g 1 flag is used in characteristic 0, the result is always probabilistic: the +leading monomials are deduced from two computations over a prime field, the first prime being +chosen randomly. + For instance, in the above example, one can deduce that the ideal has dimension 0 (finitely + + + + +many solutions with coordinates in an algebraic closure of 1073741827ℤ + ℤ + ) since the basis of leading +monomials contain pure powers of all variables. The degree of the ideal is also 8 since there are +8 monomials in 𝑧 1, 𝑧 2, 𝑧 3 which are not divisible by the above leading monomials. + msolve also allows you to perform Gröbner bases computations using one-block elimination +monomial order thanks to the -e flag. The following command + + ./msolve -e 1 -g 2 -f in.ms -o out.ms + + + + + on + + t, w, x, y, z + 1073741827 + w^4, + x^4, + w*y^3+1073741826*x*z^3, + t*z+1073741826 + + + will perform the Gröbner basis computation eliminating the first variable. The output is + + #Reduced Groebner basis data + #--- + #field characteristic: 1073741827 + #variable order: t, w, x, y, z + #monomial order: eliminating first variable, blocks: graded reverse lexicographical + #length of basis: 7 elements sorted by increasing leading monomials + #--- + [1*w^1*y^3+1073741826*x^1*z^3, + 1*x^4, + 1*w^1*x^3, + 1*w^2*x^2, + 1*w^3*x^1, + 1*w^4, + 1*t^1*z^1+1073741826]: + + + + + where we see that the first 6 polynomials are only in 𝑤, 𝑥, 𝑦, 𝑧, which corresponds to the +elimination of the variable 𝑡. When the input coefficients lie in the field of rational numbers +(hence, characteristic 0), the returned Gröbner basis is the one of the elimination ideal, i.e. they +have partial degree 0 in the variables to eliminate. + More generally, using -e k will eliminate the 𝑘 first variables. Thus, + + ./msolve -e 2 -g 2 -f in.ms -o out.ms + + + + + will eliminate 𝑡 and 𝑤, yielding + + + + + #Reduced Groebner basis data + #--- + #field characteristic: 1073741827 + #variable order: t, w, x, y, z + #monomial order: eliminating first 2 variables, blocks: graded reverse lexicographical + #length of basis: 7 elements sorted by increasing leading monomials + #--- + [1*x^4, + 1*w^1*y^3+1073741826*x^1*z^3, + 1*w^1*x^3, + 1*t^1*z^1+1073741826, + 1*w^2*x^2, + 1*w^3*x^1, + 1*w^4]: + #Reduced Groebner basis for input in characteristic 1073741827 + #for variable order t, w, x, y, z + #w.r.t. grevlex monomial ordering + #consisting of 7 elements: + [1*x^4, + 1*w^1*y^3+1073741826*x^1*z^3, + 1*w^1*x^3, + 1*t^1*z^1+1073741826, + 1*w^2*x^2, + 1*w^3*x^1, + 1*w^4]: + + + + + where we see that only the first polynomial is not in 𝑡 and 𝑤. + + +6 Parametrizations of (finitely many) solutions +Assume that the input polynomials have coefficients in some field 𝕂 with variables 𝑥 1, . . . , 𝑥𝑛 . In +the case of polynomial systems of dimension 0, msolve computes by default a zero-dimensional +parametrization of the solution set. The user can obtain such an encoding using the -P flag (see +below). + Let us recall what a rational parametrization is. This is a couple (P, ℓ) where ℓ is a linear form +𝜆1𝑥 1 + · · · + 𝜆𝑛 𝑥𝑛 with 𝜆𝑖 ∈ 𝕂 (for 1 ⩽ 𝑖 ⩽ 𝑛), P is a sequence of polynomials (𝑤, 𝑤 ′, 𝑣 1, . . . , 𝑣𝑛 ) +in 𝕂 [𝑡] where 𝑡 is a new variable such that: + • when 𝕂 is a prime field, 𝑤 ′ = 1 else 𝑤 ′ = 𝜕𝑤 + 𝜕𝑡 ; + + • deg(𝑣𝑖 ) < deg(𝑤) for 1 ⩽ 𝑖 ⩽ 𝑛; + + • 𝜆1𝑣 1 + · · · + 𝜆𝑛 𝑣𝑛 = 𝑡𝑤 ′ mod 𝑤 +and the solution set to the input polynomials coincides with the set: +    + 𝑣 1 (𝜗) 𝑣𝑛 (𝜗) + − ′ ,...,− ′ 𝑤 (𝜗) = 0 . + 𝑤 (𝜗) 𝑤 (𝜗) +In algebraic words, the polynomials 𝑤 ′𝑥𝑖 + 𝑣𝑖 belong to the radical of the ideal generated by the +input equations and the form 𝜆1𝑥 1 + · · · + 𝜆𝑛 𝑥𝑛 + 𝑡. + msolve outputs univariate polynomials as an array [deg,L] where deg is the degree of the +polynomial under consideration and L is the array of its coefficients in the monomial basis +by increasing degree and c is a denominator to all coefficients. For instance, the polynomial +𝑥 2 + 3𝑥 − 2 is encoded by + + + +[2, [-2, 3, 1]] + + We first explain msolve’s output in the case where the input coefficients are rational numbers +(the characteristic zero case). For an input in the file in.ms + + z1, z2 + 0 + z1^2+z2^2-1, + z1^2-z2^2 + + + the command + + ./msolve -P 2 -f in.ms + + + + + msolve outputs is + + [0, [0, + 3, + 4, + [’z1’, ’z2’, ’A’], + [-119/576,69/576,5/576], + [1, + [[4, [883600, 0, -18922, 0, 25]], + [3, [0, -37844, 0, 100]], + [ + [[3, [223720, 0, -1190, 0]], + 1], + [[3, [129720, 0, 690, 0]], + 1] + ]]]]]: + + + + + and has the following structure + + [0, [0, nvars, deg, vars, form, [1,[lw, lwp, param]]]]: + + + + + where + • the first 0 indicates that the input system has finitely many complex solutions (dimension + at most 0); + + • the second 0 is the characteristic; + + • nvars is the number of variables used for the parametrization (it coincides with the + number of input variables if the form ℓ is chosen as one of the variables else it is one + more); + + • deg is the number of solutions, counted with multiplicities (in other words the degree of + the ideal generated by the input equations); + + + + • vars is the list of variables following the ordering used for computing the parametrization + (hence, with maybe with one more variable than the ones given as input). + In our example, msolve outputs: + [’z1’, ’z2’, ’A’] + + where A is a new variable. + + • form is the list of coefficients for the linear form ℓ when it does not coincide with one of + the input variables (else it is an empty list); + In our example, this is a list of three rational numbers, say [-119/576,69/576,5/576], + indicating that the linear form used to compute the rational parametrization is + -119/576*z1+69/576*z2+5/576*A + + • the next 1 indicates that a single parametrization is returned next (the one encoded by + [lw, lwp, param]); + + • lw is the encoding of the eliminating polynomial 𝑤; + + • lwp is the encoding of the denominator used in the rational parametrization; + + • param is the list of the output parametrizations, there are 𝑛 − 1 where 𝑛 is the number of + elements in vars ; they are encoded as follows [[deg, L], c] where c is an integer which + divides the polynomial encoded by [deg, L]. + The first one corresponds to the first variable in vars, the second parametrization cor- + responds to the second variable in vars and so on. Hence, the variable which is used to + parametrize the solution set is always the last one. + +We illustrate now how the output looks like on input file in.ms + + z1, z2, z3 + 0 + z1^2-z2^2+z3^2-4, + z1*z2+2*z2*z3-3*z3*z1-1, + z1+2*z2+3*z3-1 + + + Using ./msolve -P 2 -f in.ms the output is + + + + + [0, [0, + 3, + 4, + [’z1’, ’z2’, ’z3’], + [0, 0, 1], + [1, + [[4, [-116, -210, 1484, -344, 53]], + [3, [-210, 2968, -1032, 212]], + [ + [[3, [1894, 162, -1636, 192]], + 1], + [[3, [-146, -620, -3118, 314]], + 1] + ]]]]]: + + + + + On this example, all variables are parametrized by the variable z3. + The polynomial 𝑤 is −116 − 210𝑧 3 + 1484𝑧 32 − 344𝑧 33 + 53𝑧 34 . The polynomials 𝑣 1 and 𝑣 2 are +respectively + 𝑣 1 = 1894 + 162𝑧 3 − 1636𝑧 32 + 192𝑧 33 and 𝑣 2 = −146 − 620𝑧 3 − 3118𝑧 32 + 314𝑧 33 . +Note that we can get both the parametrization and the real roots. For instance, using the +command ./msolve -P 1 -f in.ms, one obtains + + [0, [0, + 3, + 4, + [’z1’, ’z2’, ’z3’], + [0, 0, 1], + [1, + [[4, [-116, -210, 1484, -344, 53]], + [3, [-210, 2968, -1032, 212]], + [ + [[3, [1894, 162, -1636, 192]], + 1], + [[3, [-146, -620, -3118, 314]], + 1] + ]]]],[1, + [[[679375673646273705027530285330331715009 / 2^128, 339687836823136852513765142665165857505 / 2^127], [-60535166785954698124918883091179878673 + / 2^128, -3783447924122168632807430193198742417 / 2^124], [-1162789190151604508343028862486419979779 / 2^132, + -581394595075802254171514431243209989889 / 2^131]], [[-756665306660103909967296571629791504137 / 2^128, + -756665306660103909967296571629791504135 / 2^128], [88745898258177294078528671940999802399 / 2^126, + 177491796516354588157057343881999604799 / 2^127], [2063895933416661444279689618845660247455 / 2^132, + 4127791866833322888559379237691320494911 / 2^133]]] + ]]: + + + + + We end this section with the same example as above but seeing the coefficients in ℤ/65521ℤ. + + z1, z2, z3 + 65521 + z1^2-z2^2+z3^2-4, + z1*z2+2*z2*z3-3*z3*z1-1, + z1+2*z2+3*z3-1 + + + The call ./msolve -P 2 -f in.ms then outputs + + + + + [0, [65521, + 3, + 4, + [’z1’, ’z2’, ’z3’], + [0, 0, 1], + [1, + [[4, + [16069, 9886, 28, 2466, 1]], + [0, + [1]], + [ + [[3, + [6276, 37054, 57744, 4959]]], + [[3, + [29622, 14235, 36649, 30281]]] + ]]]]]: + + + + +7 Saturation and colon ideals +msolve also proposes algorithms for computing Gröbner bases of saturation and colon ideals. +Given 𝑚 + 1 polynomials 𝑓1, . . . , 𝑓𝑚 , 𝜑 over a field 𝕂 with variables 𝑥 1, . . . , 𝑥𝑛 , the saturation +ideal ⟨𝑓1, . . . , 𝑓𝑚 ⟩ : ⟨𝜑⟩ ∞ is the ideal of all polynomials ℎ, such that there exists 𝑘 ∈ ℕ such that +ℎ𝜑 𝑘 ∈ ⟨𝑓1, . . . , 𝑓𝑚 ⟩. The colon ideal ⟨𝑓1, . . . , 𝑓𝑚 ⟩ : ⟨𝜑⟩ is the ideal of all polynomials ℎ, such that +ℎ𝜑 ∈ ⟨𝑓1, . . . , 𝑓𝑚 ⟩. + A Gröbner basis for the grevlex order can be computed in the former case with an input file +containing 𝑓1, . . . , 𝑓𝑚 , 𝜑 and called with the flag -S to use the F4SAT algorithm. Note that this +option is at the moment restricted to 32 bit prime fields. + For instance, consider the following input to msolve written in a file in.ms. + + w, x, y, z + 1073741827 + w^4, + x^4, + 1073741826*x*z^3+w*y^3, + z + + + Then, typing the following command line + + ./msolve -S -g 2 -f in.ms -o out.ms + + + + + will display in the out.ms file the following content. + + + + + #Reduced Groebner basis data + #--- + #field characteristic: 1073741827 + #variable order: w, x, y, z + #monomial order: graded reverse lexicographical + #length of basis: 6 elements sorted by increasing leading monomials + #--- + [1*w^1*y^3+1073741826*x^1*z^3, + 1*x^4, + 1*w^1*x^3, + 1*w^2*x^2, + 1*w^3*x^1, + 1*w^4]: + + + + +8 More flags and options + • The flag -h or --help displays some documentation + + • The flag -v or --verbose controls the verbosity + Default value: 0 + + • The flag -t or --threads controls the number of threads used + Default value: 1 + + • The flag -p or --precision controls the binary precision of the output of + the univariate real root solver (default value may be automatically increased by msolve + when needed). + Default value:128 + + • The flag -g or --groebner-basis tells msolve to output the leading monomial of + the ideal generated by the input polynomials (when is 1) or the minimal reduced + Gröbner basis (when is 2 and a prime characteristic is indicated). + Default value:0 + + • The flag -P or --precision tells msolve to output the rational parametriza- + tion computed for solving zero-dimensional polynomial systems (those with finitely many + solutions in an algebraic closure of the base field). When -P 0 is set, such a parametrization + is not returned, when -P 1 is set, the parametrization is returned and, in the characteristic + zero case (rational coefficients), real solutions are returned, when -P 2 is set, only the + rational parametrization is returned. + Default value:0 + + • The flag -c tells msolve how to handle genericity requirements: when is + 0 msolve quits when these requirements are not satisfied, when is 1 msolve is + allowed to change the order of the variables if needed and quits if after these changes, the + genericity requirements are not satisfied, when is 2 msolve is allowed to introduce + + + + a new variable and a linear form until the genericity requirements are satisfied. In + positive characteristic, this linear have random coefficients, while in characteristic 0, it is + deterministically chosen, depending on the input. + Default value:2 + + • The flag -d tells msolve how to handle further genericity requirements when the + staircase is not generic enough by computing some normal forms: can go from 0 + (no normal form computations are computed) to 4 (all the normal forms are computed). + Default value:2 + + • The flag --random-seed tells msolve which seed must be used to initialize the + pseudo-random generator: -1 means that time(0) is used so that the seed is based on + current time, otherwise, for any nonnegative integer N, N will be the seed. The latter + option is for debug purpose only as the lack of randomization can lead to failures on some + input. + Default value:0 + + + diff --git a/apn/lean/docs/nauty/COPYRIGHT b/apn/lean/docs/nauty/COPYRIGHT new file mode 100644 index 00000000..d826b92a --- /dev/null +++ b/apn/lean/docs/nauty/COPYRIGHT @@ -0,0 +1,44 @@ +This is the license for the software package Nauty and +Traces, package versions 2.6r3 and later. + +Five categories of software are included in the package: +A. All files not listed as B-G below, copyright Brendan McKay (1984-) +B. Files traces.h, traces.c and dretodot.c, copyright Adolfo Piperno (2008-) +C. File watercluster2.c and genposetg.c, copyright Gunnar Brinkmann (2009-) +D. Files planarity.h and planarity.c, copyright Magma project. +E. Files nautycliquer.h and nautycliquer.c, copyright to Sampo + Niskanen and Patric Östergård. +F. Much of file nauchromatic.c, copyright Gordon Royle. +G. The code in nausha.c was put into the public domain by Brad Conte. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this software except in compliance with the License. +A copy of the License is included in the package and can also +be viewed at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +Brendan McKay: Australian National University; Brendan.McKay@anu.edu.au +Adolfo Piperno: University of Rome "Sapienza"; piperno@di.uniroma1.it +Gunnar Brinkmann: University of Ghent; Gunnar.Brinkmann@UGent.be +Magma Administration: University of Sydney; admin@maths.usyd.edu.au +Patric Ostergard: Aalto Univerity; patric.ostergard@aalto.fi + +---END-OF-FORMAL-COPYRIGHT-NOTICE--- + +Earlier (pre-2.6) versions of this package carried a different +notice: "Permission is hereby given for use and/or distribution +with the exception of sale for profit or application with nontrivial +military significance." These days most people use nauty via a +larger package such as Magma, Sage, or GAP, and often they don't +even know they are using nauty. Due to the legal nonsense that +large package distributors need to worry about, it has proved too +much trouble to maintain an idiosyncratic licence. I didn't change +my opinion about military use, but it is no longer part of the +formal notice. Brendan McKay (Jan 20, 2016) diff --git a/apn/lean/docs/nauty/LICENSE b/apn/lean/docs/nauty/LICENSE new file mode 100644 index 00000000..d6456956 --- /dev/null +++ b/apn/lean/docs/nauty/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/apn/lean/docs/nauty/nauty-guide.txt b/apn/lean/docs/nauty/nauty-guide.txt new file mode 100644 index 00000000..eac5f3fa --- /dev/null +++ b/apn/lean/docs/nauty/nauty-guide.txt @@ -0,0 +1,2039 @@ + + +15 Utilities +The nauty package includes a suite of programs called gtools that provide efficient +processing of files of graphs stored in graph6, sparse6 or digraph6 format. These formats +are defined in Section 20. + Most of the gtools programs will run on any system with a modern C compiler, but +a few need Unix-like facilities. For example, the program shortg requires a program +compatible with the Unix sort program, as well as the popen system routine. + A general principle is that data is sent to stdout (unless an alternative output file is +named) and diagnostic output is sent to stderr. + All the gtools programs are self-documenting: just execute with the option --help +to see an explanation of all the features. We only list the basic functions of the programs +here; see Section 24 for more details. + +addedgeg : add an edge in each possible way +addptg : add extra vertices in various ways +amtog : read graphs in adjacency matrix form +ancestorg : remove some final vertices from graphs +assembleg : form graphs whose components are input graphs +biplabg : label bipartite graphs so the colour classes are contiguous +catg : concatenate files of graphs +complg : complement graphs +converseg : converse digraphs +copyg : convert format and select subset +countg : count graphs according to a variety of properties +cubhamg : find hamiltonian cycles in subcubic graphs +deledgeg : delete an edge in each possible way +delptg : delete some vertices in each possible way +dimacs2g : read files of graphs in DIMACS format +directg : generate small digraphs with given underlying graph +dretodot : read graphs in dreadnaut form and write in dot format for drawing +dretog : read graphs in dreadnaut form +edgetransg : select by group action on vertices, edges and arcs +genbg : generate small bicoloured graphs + +geng : generate small graphs +genposetg : generate posets +genquartic : generate quartic graphs +genrang : generate random graphs +genspecialg : generate special graphs, like cycles and complete graphs +gentourng : generate small tournaments +gentreeg : generate trees +genktreeg : generate k-trees +hamheuristic : try to find hamiltonian cycles in any graphs, without guaranteed success +labelg : canonically label graphs +linegraphg : make the linegraphs of a file of graphs +listg : display graphs in a variety of forms +multig : generate small multigraphs with given underlying graph +newedgeg : in each possible way, subdivide two non-adjacent edges and join the two new + vertices +nbrhoodg : extract neighbourhood graphs +newedgeg : subdivide non-adjacent edges and join the new vertices +NRswitch : switch the edges between the neighbourhood and the complementary neigh- + bourhood, for each vertex +pickg : select graphs according to a variety of properties +planarg : test graphs for planarity and find embeddings or obstructions. +productg : make product of two graphs +ranlabg : randomly relabel graphs +ransubg : random subgraph or orientation +shortg : remove isomorphs from a file of graphs +showg : a stand-alone limited subset of listg +subdivideg : make the subdivision graphs of a file of graphs +twohamg : split quartic graphs into two hamiltonian cycles +underlyingg : undirected graph underlying directed graph +uniqg : select non-isomorphic graphs +vcolg : colour the vertices of graphs in all distinct ways +watercluster2 : an alternative to directg which is usually faster + + Further programs will be added. Requests are welcome. + + +19 Advanced geng usage +Several of the programs have the facility to compile user code into them in a way that +influences their behaviour. The technical details are described inside the source code of +those programs, For example, if P is a graph property that is preserved on removing a +vertex (such as absence of a particular subgraph), then geng can generate graphs with that +property more efficiently than filtering at the end. An example is in the file no4holes.c. +/* This is a demonstration plugin for geng. Its function is to remove + graphs containing an induced cycle of length 4. +A typical compilation command would be + gcc -o no4holes -DMAXN=WORDSIZE -O3 -march=native -DPRUNE=no4holes \ + geng.c no4holes.c nauty1.a + +PREPRUNE could be used in place of PRUNE -- adopt whichever is fastest. +The resulting executable will have all the features of geng but also graphs +with induced cycles of length 4 will be excluded. */ + +#include "gtools.h" + +int +no4holes(graph *g, int n, int maxn) +/* n is the size of the current graph and maxn is the output size. The most + recent vertex added was vertex n-1 and the graph without that vertex has + already been tested. So all we need to do is look for induced cycles of + length 4 which include vertex n-1. If we find one, we return 1 to make sure + this graph and its descendants are not output. Otherwise, we return 0. + Note that graphs generated by geng have at most WORDSIZE vertices, and + so we can use a single setword to hold a set of vertices. */ +{ + setword x,y,z; + int i,j; + + x = g[n-1]; /* Neighbours of n-1 */ + while (x) + { + TAKEBIT(i,x); /* i is next neighbour; remove it from x */ + y = x & ~g[i]; /* Later neighbours of n-1, not adjacent to i */ + z = g[i] & ~g[n-1] & ~bit[n-1]; /* Neighbours of i that are + non-neighbours of n-1 */ + while (y) + { + TAKEBIT(j,y); /* Second neighbour of n-1 */ + if ((g[j] & z)) return 1; /* Found 4-hole */ + } + } + return 0; +} + +20 Graph formats used by the utilities + +This is the file formats.txt. + + +Description of graph6, sparse6 and digraph6 encodings +----------------------------------------------------- +Brendan McKay, brendan.mckay@anu.edu.au +Updated Jun 2015, Apr 2022, Aug 2023. + +General principles: + + All numbers in this description are in decimal unless obviously + in binary. + + The character code used in all cases is ASCII, but no bytes are + present which would cause ambiguity if the file is read as UTF8. + + Apart from the header, there is one object per line. Apart from + the header, end-of-line characters, and the characters ":", ";" + and "&" which might start a line, all bytes have a value in the + range 63-126 (which are all printable ASCII characters). A file of + objects is a text file, so whatever end-of-line convention is + locally used is fine; however the C library input routines must + show the standard single-LF end of line to programs). + +Bit vectors: + + A bit vector x of length k can be represented as follows. + Example: 1000101100011100 + + (1) Pad on the right with 0 to make the length a multiple of 6. + Example: 100010110001110000 + + (2) Split into groups of 6 bits each. + Example: 100010 110001 110000 + + (3) Add 63 to each group, considering them as bigendian binary numbers. + Example: 97 112 111 + + These values are then stored one per byte. + So, the number of bytes is ceiling(k/6). + + Let R(x) denote this representation of x as a string of bytes. + +Small nonnegative integers: + + + Let n be an integer in the range 0-68719476735 (2^36-1). + + If 0 <= n <= 62, define N(n) to be the single byte n+63. + If 63 <= n <= 258047, define N(n) to be the four bytes + 126 R(x), where x is the bigendian 18-bit binary form of n. + If 258048 <= n <= 68719476735, define N(n) to be the eight bytes + 126 126 R(x), where x is the bigendian 36-bit binary form of n. + + Examples: N(30) = 93 + N(12345) = N(000011 000000 111001) = 126 66 63 120 + N(460175067) = N(000000 011011 011011 011011 011011 011011) + = 126 126 63 90 90 90 90 90 + + +Description of graph6 format. +---------------------------- + +Data type: + simple undirected graphs of order 0 to 68719476735. + +Optional Header: + >>graph6<< (without end of line!) + +File name extension: + .g6 + +One graph: + Suppose G has n vertices. Write the upper triangle of the adjacency + matrix of G as a bit vector x of length n(n-1)/2, using the ordering + (0,1),(0,2),(1,2),(0,3),(1,3),(2,3),...,(n-2,n-1). + + Then the graph is represented as N(n) R(x). + +Example: + Suppose n=5 and G has edges 0-2, 0-4, 1-3 and 3-4. + + x = 0 10 010 1001 + + Then N(n) = 68 and R(x) = R(010010 100100) = 81 99. + So, the graph is 68 81 99. + + +Description of sparse6 format. +------------------------------ + +Data type: + Undirected graphs of order 0 to 68719476735. + Loops and multiple edges are permitted. + + + (However, as of May 2022, the utilities in the nauty package + and nauty itself do not support multiple edges and some + utilities do not support loops either.) + +Optional Header: + >>sparse6<< (without end of line!) + +File name extension: + .s6 + +General structure: + + Each graph occupies one text line. Except for the first character + and end-of-line characters, each byte has the form 63+x, where + 0 <= x <= 63. The byte encodes the six bits of x. + + The encoded graph consists of: + (1) The character ’:’. (This is present to distinguish + the code from graph6 format.) + (2) The number of vertices. + (3) A list of edges. + (4) end-of-line + + Loops and multiple edges are supported, but not directed edges. + +Number of vertices n: + + 1, 4, or 8 bytes N(n) as above. + This is the same as graph6 format. + +List of edges: + + Let k be the number of bits needed to represent n-1 in binary. + + The remaining bytes encode a sequence + + b[0] x[0] b[1] x[1] b[2] x[2] ... b[m] x[m] + + Each b[i] occupies 1 bit, and each x[i] occupies k bits. + Pack them together in bigendian order, and pad up to a + multiple of 6 as follows: + 1. If (n,k) = (2,1), (4,2), (8,3) or (16,4), and vertex + n-2 has an edge but n-1 doesn’t have an edge, and + there are k+1 or more bits to pad, then pad with one + 0-bit and enough 1-bits to complete the multiple of 6. + 2. Otherwise, pad with enough 1-bits to complete the + multiple of 6. + These rules are to match the gtools procedures, and to avoid + + + the padding from looking like an extra loop in unusual cases. + + Then represent this bit-stream 6 bits per byte as indicated above. + + The vertices of the graph are 0..n-1. + The edges encoded by this sequence are determined thus: + + v = 0 + for i from 0 to m do + if b[i] = 1 then v = v+1 endif; + if x[i] > v then v = x[i] else output {x[i],v} endif + endfor + + In decoding, an incomplete (b,x) pair at the end is discarded. + +Example: + + :Fa@x^ + + ’:’ indicates sparse6 format. + Subtract 63 from the other bytes and write them in binary, + six bits each. + + 000111 100010 000001 111001 011111 + + The first byte is not 63, so it is n. n=7 + n-1 needs 3 bits (k=3). Write the other bits in groups + of 1 and k: + + 1 000 1 000 0 001 1 110 0 101 1 111 + + This is the b/x sequence 1,0 1,0 0,1 1,6 0,5 1,7. + The 1,7 at the end is just padding. + The remaining parts give the edges 0-1 0-2 1-2 5-6. + + +Description of incremental sparse6 format. +----------------------------------------- + + This is an extension to sparse6 format that is very efficient if most + graphs in a file are similar to the previous graph. + + Each graph occupies one text line. Except for the first character + and end-of-line characters, each byte has the form 63+x, where + 0 <= x <= 63. The byte encodes the six bits of x. + + The encoded graph consists of: + (1) The character ’;’. + + + (2) A list of edges. + (3) end-of-line + + This cannot appear as the first graph in a file. The number of vertices + is taken to be equal to the number of vertices in the previous graph. + The list of edges specifies the symmetric difference of this graph and + the previous graph. It is encoded exactly the same as part (3) of + sparse6 format. + + Loops are supported, but not multiple edges. + + +Description of digraph6 format. +------------------------------ + +Data type: + simple directed graphs (allowing loops) of order 0 to 68719476735. + +Optional Header: + >>digraph6<< (without end of line!) + +File name extension: + .d6 + +One graph: + Suppose G has n vertices. Write the adjacency matrix of G + as a bit vector x of length n^2, row by row. + + Then the graph is represented as ’&’ N(n) R(x). + The character ’&’ (decimal 38) appears as the first character. + +Example: + Suppose n=5 and G has edges 0->2, 0->4, 3->1 and 3->4. + + x = 00101 00000 00000 01001 00000 + + Then N(n) = 68 and + R(x) = R(00101 00000 00000 01001 00000) = 73 63 65 79 63. + So, the graph is 38 68 73 63 65 79 63. + +Note: + SageMath has a format also called "digraph6" that is different + from this one. The leading "&" is omitted and the direction of + every edge is reversed. + + + For a description of the planarcode and edgecode formats, see the plantri docu- +mentation at https://users.cecs.anu.edu.au/∼bdm/plantri/. + +24 Help texts for the utilities + +===== addedgeg ====================================================== + +Usage: addedgeg [-lq] [-D#] [-btfF] [-z#] [infile [outfile]] + +For each edge nonedge e, output G+e if it satisfies certain conditions + + The output file has a header if and only if the input file does. + + -l Canonically label outputs + -D# Specify an upper bound on the maximum degree of the output + -b Output has no new cycles of odd length + -t Output has no new 3-cycle if input doesn’t + -f Output has no new 4-cycle if input doesn’t + -F Output has no new 5-cycle if input doesn’t + -z# Output has no new cycles of length less than # + -btfFz can be used in arbitrary combinations + -q Suppress auxiliary information + +===== addptg ====================================================== + +Usage: addptg [-lq] [-n#] [-j#:#] [-e#:#] [-ck] [-io] [infile [outfile]] + +Add a specified number of new vertices + + The output file has a header if and only if the input file does. + + -l canonically label outputs + -c join each new vertex to all the old vertices + -k make a clique on the set of new vertices + -n# the number of new vertices (default 1) + -j# -j#:# join a new vertex to # old vertices in all possible ways + -e# -e#:# use all joins that give the new graphs # edges + (-j, -e, -D are each incompatible with -n) + -D# upper bound on the maximum (out)degree of the output graphs + -i for a digraph, edges go towards the old vertices + -o for a digraph, edges go away from the old vertices + (-i is the default if neither -i nor -o is given) + -q Suppress auxiliary information + + + + +===== amtog ====================================================== + +Usage: amtog [-n#sgzhq] [-o#] [infile [outfile]] + +Read graphs in matrix format. + + -n# Set the initial graph order to # (no default). + This can be overridden in the input. + -g Write the output in graph6 format (default). + -s Write the output in sparse6 format. + -z Write the output in digraph6 format. + -h Write a header (according to -g or -s). + -w Don’t warn about loops (which are suppressed for -g) + -q Suppress auxiliary information. + -o# Treat digit # as 1 and other digits as 0. + + Input consists of a sequence of commands restricted to: + + n=# set number of vertices (no default) + The = is optional. + m Matrix to follow + An ’m’ is also assumed if a digit is encountered. + M Complement of matrix to follow (as m) + t Upper triangle of matrix to follow, row by row + excluding the diagonal. + T Complement of upper trangle to follow (as t) + s Upper triangle of matrix to follow, row by row + excluding the diagonal; lower triangle is complement. + q exit (optional) + +===== ancestorg ====================================================== + +Usage: ancestorg [-q] [-g#:#|-g#] [infile [outfile]] + +The g-th generation ancestor of a graph is the graph obtained by removing + the final g vertices. The 0-th generation ancestor is the graph itself. + For each input graph, write the ancestors whose generation is given by the + g argument. No zero-sized graphs are written. + Output is always in graph6 format. + + The output file has a header if and only if the input file does. + + -g# -g#:# Specify a generation or range of generations (default: all) + -q Suppress auxiliary information + + + + +===== assembleg ====================================================== + +Usage: assembleg -n#|-n#:# [-i#|i#:#] [-k#|k#:#] [-L] [-q] [-c] [infile [outfile]] + +Assemble input graphs as components of output graphs. + + The output file has no header. + If the input has any directed graphs, all outputs are directed. + Otherwise, the output format is determined by the header + or first input. + The input graphs had better all fit into memory at once, + unless -L is given, in which case only the graphs of at + most half the output size are stored at once. + The output graphs will be non-isomorphic if the input + graphs are connected and non-isomorphic. + + -n# -n#:# Give range of output sizes (compulsory) + -i# -i#:# Give range of input sizes to use + -k# -k#:# How many input graphs to combine (default -k2:) + -L Assume all input graphs strictly larger than maxn/2 + vertices follow any smaller graphs in the input, + where maxn is the largest size specified by -n. + This can greatly reduce memory consumption. + -c Also write graphs consisting of a single input + (equivalent to -k1:, overridden by -k) + -u Generate the graphs but don’t write them + -q Suppress auxiliary information. + +===== biplabg ====================================================== + +Usage: biplabg [-q] [infile [outfile]] + +Label bipartite graphs so that the colour classes are contiguous. + The first vertex of each component is assigned the first colour. + Vertices in each colour class have the same relative order as before. + Non-bipartite graphs are rejected. + + The output file has a header if and only if the input file does. + + -q Suppress auxiliary information. + +===== catg ====================================================== + +Usage: catg [-xv] [infile]... + + Copy files to stdout with all but the first header removed. + + -x Don’t write a header. + + + In the absence of -x, a header is written if + there is one in the first input file. + + -v Summarize to stderr. + +===== complg ====================================================== + +Usage: complg [-lq] [-a] [-L] [-r|-R] [infile [outfile]] + +Take the complements of a file of graphs. + + The output file has a header if and only if the input file does. + The output format is defined by the header or first graph. + + -r Only complement if the complement has fewer directed edges. + -R Only complement if the complement has fewer directed edges + or has the same number of directed edges and is canonically + less than the original. + -a Also output the input graph (before the complement). + -L Complement the loops too. By default, preserve them. + -l Canonically label outputs. + -q Suppress auxiliary information. + +===== converseg ====================================================== + +Usage: converseg [-q] [-a|-c] [infile [outfile]] + +Take the converse digraphs of a file of directed graphs. + + The output file has a header if and only if the input file does. + Undirected graphs are passed through without change, while + directed graphs are written in digraph6 format. + + -a Also output the original graph (before the converse) + -c Output only self-converse digraphs + + -q Suppress auxiliary information. + +===== copyg ====================================================== + +Usage: copyg [-gszfp#:#qhx] [infile [outfile]] + + Copy a file of graphs with possible format conversion. + + -g Use graph6 format for output + -s Use sparse6 format for output + -z Use digraph6 format for output + -i Use incremental sparse6 format for output + + + In the absence of -g, -s, -z or -i, the format + depends on the header or, if none, the first input line. + As an exception, digraphs are always written in digraph6. + + -p# -p#:# + Specify range of input lines (first is 1) + This can fail if the input has incremental lines. + -f With -p, assume input lines of fixed length + (ignored if header or first line has sparse6 format). + -I# Have at most this number of incremental steps + in a row. Implies -i. + + -h Write a header. + -x Don’t write a header. + In the absence of -h and -x, a header is written if + there is one in the input. + + -q Suppress auxiliary output. + +===== countg ====================================================== + +Usage: [pickg|countg] [-fp#:#q -V -X] [--keys] [-constraints -v] [ifile [ofile]] + +countg : Count graphs according to their properties. + pickg : Select graphs according to their properties. + + ifile, ofile : Input and output files. + ’-’ and missing names imply stdin and stdout. + + Miscellaneous switches: + -p# -p#:# Specify range of input lines (first is 1) + May fail if input is incremental. + -f With -p, assume input lines of fixed length + (only used with a file in graph6/digraph6 format) + -v Negate all constraints (but not -p) + -X Reverse selection (but -p still observed) + -V List properties of every input matching constraints. + -l Put a blank line whenever the first parameter changes, + if there are at least two parameters. + -1 Write output as lines of numbers separated by spaces, + with 0/1 for boolean and both endpoints of ranges given + separately even if they are the same, and the count at + the end of the line. Also, no total is written. + -2 The same as -1 but counts are not written. + -9 Flush the output after each graph (expensive if many graphs) + -q Suppress informative output. + + Constraints: + + + Numerical constraints (shown here with following #) can take + a single integer value, or a range like #:#, #:, or :#. Each + can also be preceded by ’~’, which negates it. (For example, + -~D2:4 will match any maximum degree which is _not_ 2, 3, or 4.) + Constraints are applied to all input graphs, and only those + which match all constraints are counted or selected. + + -n# number of vertices -e# number of edges + -ee# number of non-edges (including loops for digraphs) + -L# number of loops -C strongly connected + -LL# number of 2-cycles -cc# number of components + -d# minimum (out-)degree -D# maximum (out-)degree + -m# vertices of min (out-)degree -M# vertices of max (out-)degree + -u# minimum (in-)degree -U# maximum (in-)degree + -s# vertices of min (in-)degree -S# vertices of max (in-)degree + -r regular -b bipartite + -z# radius -Z# diameter + -g# girth (0=acyclic) -Y# total number of cycles + -h# maximum independent set -k# maximum clique + -T# number of triangles -K# number of maximal cliques + -TT# number independent 3-sets -P# number of 5-cycles + -B# smallest possible first side of a bipartition (0 if nonbipartite) + -H# number of induced cycles -W# number of 4-cycles + -E Eulerian (all degrees are even, connectivity not required) + -a# group size -o# orbits -F# fixed points -t vertex-transitive + -O# number of orbits of edges -OO# number of orbits of arcs + -tt# 1 = edge transitive, 2 = arc transitive, 0 = neither + -c# connectivity (2 means 2 or more). + -kk# #-tree, otherwise 0. The complete graph K_n is tabulated as + an n-tree, but matches either n-1 or n, + -i# min common nbrs of adjacent vertices; -ii# maximum + -j# min common nbrs of non-adjacent vertices; -jj# maximum + -x# number of sources -xx# number of sinks + -WW# number of diamonds -HH# number of hexagons + -N# chromatic number (limited to WORDSIZE colours) + -NN# chromatic index (limited to max degree WORDSIZE-1) + -A# class (chromatic index - maximum degree + 1) + -G# connectivity -GG# edge connectivity + +Sort keys: + Counts are made for all graphs passing the constraints. Counts + are given separately for each combination of values occurring for + the properties listed as sort keys. A sort key is introduced by + ’--’ and uses one of the letters known as constraints. These can + be combined: --n --e --r is the same as --ne --r and --ner. + The order of sort keys is significant. + A comma can be used as a separator. +The sort key ’:’ has a special purpose: the values of sort keys + + + following ’:’ are given as ranges rather than creating a separate + line for each value. For example --e:zZ will give the ranges of + radius and diameter that occur for each number of edges. + The output format matches the input, except that sparse6 is used + to output an incremental graph whose predecessor is not output. + + Some sort keys have boolean variants with parameters: + --N# #-colourable (i.e. chromatic number <= #) + --NN# #-edge colourable + --G# #-connected (i.e. connectivity >= #) + --GG# #-edge connected + +===== countneg ====================================================== + +Usage: countneg [-ne] [infile] + + Count graphs by number of vertices and/or number of edges + + -n Count by vertices + -e Count by edges + Default and -ne are to count by both + -q Suppress auxiliary output. + Use countg instead if incremental inputs are present. + +===== cubhamg ====================================================== + +Usage: cubhamg [-#] [-v|-V] [-n#-#|-y#-#|-i|-I|-o|-O|-x|-e|-E] [-b|-t] [infile [outfile]] + +cubhamg : Find hamiltonian cycles in sub-cubic graphs + Graphs that are not hamiltonian, or not solved, are written out + infile is the name of the input file in graph6/sparse6 format + outfile is the name of the output file in the same format + + stdin and stdout are the defaults for infile and outfile + + The output file will have a header + if and only if the input file does. + + Optional switches: + + -# A parameter useful for tuning (default 100) + -v Report nonhamiltonian graphs and noncubic graphs + -V .. in addition give a cycle for the hamiltonian ones + (with -c, give count for each input) + -n#-# If the two numbers are v and i, then the i-th edge + out of vertex v is required to be not in the cycle. + It must be that i=1..3 and v=0..n-1. + -y#-# If the two numbers are v and i, then the i-th edge + + + out of vertex v is required to be in the cycle. + It must be that i=1..3 and v=0..n-1. + You can use any number of -n/-y switches to force edges. + Out of range first arguments are ignored. + If -y and -n specify the same edge, -y wins. + -i Test + property: for each edge e, there is a hamiltonian + cycle using e. + -I Test ++ property: for each pair of edges e,e’, there is + a hamiltonian cycle which uses both e and e’. + -o Test - property: for each edge e, there is a hamiltonian + cycle avoiding e + -O Test -- property: for each pair of nonadjacent edges e,e’s, + there is a hamiltonian cycle avoiding both. Note that + this is trivial unless the girth is at least 5. + -x Test +- property: for each pair of edges e,e’, there is + a hamiltonian cycle which uses e but avoids e’. + -e Test 3/4 property: for each edge e, at least 3 of the 4 + paths of length 3 passing through e lie on hamiltonian cycles. + -E Test 3/4+ property: for each edge e failing the 3/4 property, + all three ways of joining e to the rest of the graph are + hamiltonian avoiding e. + -T# Specify a timeout, being a limit on how many search tree + nodes are made. If the timeout occurs, the graph is + written to the output as if it is nonhamiltonian. + -R# Specify the number of repeat attempts for each stage. + -F Analyze covering paths from 2 or 4 vertices of degree 2. + + -b Require biconnectivity + -t Require triconnectivity (note: quadratic algorithm) + + -c Count hamiltonian cycles, output count for each graph. + -V, -n and -y can also be used. No graphs are output. + + -y, -n, -#, -R and -T are ignored for -i, -I, -x, -o, -e, -E, -F + +===== deledgeg ====================================================== + +Usage: deledgeg [-lq] [-v#] [-d#] [-z] [infile [outfile]] + +For each edge e, output G-e + + The output file has a header if and only if the input file does. + + -z Consider as digraph and delete directed edges + -l Canonically label outputs + -v# Only delete edges incident to this vertex (as head for digraph) + -d# Specify a lower bound on the minimum out-degree of the output + -q Suppress auxiliary information + + +===== delptg ====================================================== + +Usage: delptg [-lq] [-a|-b] [-d#|-d#:#] [-v#|-v#:#] [-A] [-r#] [-k#] [-n#] [-m#|-i] [infile + +Delete some vertices from a file of graphs. + + The output file has a header if and only if the input file does. + No isomorph reduction is done. + + -l Canonically label outputs + -d# -d#:# Only remove vertices with original degree in the given range + -k# Find the #-core (recursively remove vertices of degree less than k) + -n# The number of vertices to delete (default 1). + -A Delete all the vertices specified by -d and/or -v + -v# -v#:# Vertex number or numbers that it is allowed to delete + (the first vertex is number 0). + -m# Lower bound on minimum degree of output graphs. + -r# Choose # random sets of points (not necessarily different) + -S# Set random number seed (taken from clock otherwise). + -a The deleted points must be adjacent. + -b The deleted points must be non-adjacent. + -i Leave deleted vertices as isolates, not compatible with -m. + No empty graphs are output. No warning is issued if + -d, -v -n, -m together imply no graphs are output. + For digraphs, out-degree is used for -d and -m. + -q Suppress auxiliary information + +===== dimacs2g ====================================================== + +Usage: dimacs2g [-n#:#] [-a"string"] [-b"string"] [-d] -[c] [infile...] + +Read files of graphs in Dimacs format and write them to stdout. + + -d Use dreadnaut format (default is sparse6) + -n#:# Specify a range of n values for output + -a"string" A string to write before each graph. + -b"string" A string to write after each graph. + -a and -b only operate for dreadnaut output; + and should be given in separate arguments. + -c Don’t copy "c" comments from the input. + + Input files with name *.gz are ungzipped. + + + + +===== directg ====================================================== + +Usage: directg [-q] [-u|-T|-G] [-V] [-o|-a] [-f#] [-e#|-e#:#] [-s#/#] [infile [outfile]] + +Read undirected graphs and orient their edges in all possible ways. + Edges can be oriented in either or both directions (3 possibilities). + Isomorphic directed graphs derived from the same input are suppressed. + If the input graphs are non-isomorphic then the output graphs are also. + + -e# | -e#:# specify a value or range of the total number of arcs + -o orient each edge in only one direction, never both + -a only make acyclic orientations (implies -o) + -f# Use only the subgroup that fixes the first # vertices setwise + + -T use a simple text output format (nv ne edges) instead of digraph6 + -G like -T but includes group size as third item (if less than 10^10) + The group size does not include exchange of isolated vertices. + -V only output graphs with nontrivial groups (including exchange of + isolated vertices). The -f option is respected. + -u no output, just count them + -s#/# Make only a fraction of the orientations: The first integer is + the part number (first is 0) and the second is the number of + parts. Splitting is done per input graph independently. + -q suppress auxiliary information + +===== distgraphg ====================================================== + +Usage: distgraphg [-e|o|i] [-d#|-d#:#]... [-q] [infile [outfile]] + +Form graphs defined by distances in the input graphs. The -d,-e,-o-i + parameters define a set of distances. The output graph has an edge + if the distance in the input graph is in the set. + + -d# -d#:# Specify a range of allowed distances. + Can be repeated up to 100 times. + -i Include infinity (unreachable vertices) + -e, -o Only allow even or odd distances + + If none of -d,-e,-o,-i is present, the square of the graph is taken. + If -e or -o appear without -d, all even or all odd distances are allowed. + + The output file has a header if and only if the input file does. + + -q Suppress auxiliary information. + + + + +===== dretodot ====================================================== + +Usage: dretodot [-S#:#ixF#o#m#n#r#:#[r#]d#g] [infile.dre [outfile.dot [outfile.dre]]] + + Read graphs and initial coloring in dreadnaut format. +Write graphs in dot format to outfile.dot. +If outfile.dre is given, write the input graph and the partition, +as modified by the -F and -i options, to outfile.dre. outfile.dre +is allowed to be the same file as infile.dre. +-V Set max number of vertices (default 1000). +-E Set max number of edges (default 5000). +-v Set verbose mode (default NO). +-S#:# Set maximum width and height of the drawing, in inches +(default 10 x 6.18). +-i Refine the partition before drawing (default NO). +-x Draw the orbit partition, computed by Traces. (default NO). +-F# Individualize vertex # (and refine the partition). +-o# Label vertices starting at # (default 0). This can be +overridden in the input. +-m# Set the drawing model (see http://www.graphviz.org): +0 (or any value different from 1,...,5)=dot (default 0), +1=neato, 2=fdp, 3=sfdp, 4=twopi, 5=circo. +-n# Scale the size of vertices in the drawing (#=0,1,2; default 1). +-r#:# (-r#) Set the vertices to be drawn at the topmost level +in a hierarchical (dot model) drawing (default none). +Any sequence of -r#:# (r#) options is allowed. +-d# Draw the graph induced by vertices at topmost level +and by vertices at distance # from them; example: +./dretodot -n2 -r1 -r12:17 -d2 MyGraph.dre Outfile.dot. +-g Highlight the induced subgraph into the whole graph. + +Only dreadnaut commands $,$$,g,n,f,",! are recognised; no digraphs. + +===== dretog ====================================================== + +Usage: dretog [-n#o#sghq] [infile [outfile]] + +Read graphs in dreadnaut format. + + -o# Label vertices starting at # (default 0). + This can be overridden in the input. + -n# Set the initial graph order to # (no default). + This can be overridden in the input. + -g Use graph6 format (default for undirected graphs). + -z Use digraph6 format (default for directed graphs). + -s Use sparse6 format. + -h Write a header (according to -g, -z or -s). + -q Suppress auxiliary output. + + + Input consists of a sequence of dreadnaut commands restricted to: + + n=# set number of vertices (no default) + The = is optional. + $=# set label of first vertex (default 0) + The = is optional. + d indicate graph will be directed + $$ return origin to initial value (see -o#) + ".." and !..\n comments to ignore + g specify graph to follow (as dreadnaut format) + Can be omitted if first character of graph is a digit or ’;’. + q exit (optional) + +===== edgetransg ====================================================== + +Usage: edgetransg [-t] [-q] [infile [outfile]] + +Select undirected graphs according to group action on vertices, edges and arcs. + Digraphs are not supported yet. + + The output file has a header if and only if the input file does. + + -v require vertex-transitive + -V require not vertex-transitive + -e require edge-transitive + -E require not edge-transitive + -a require arc-transitive + -A require not arc-transitive + -q Suppress auxiliary information. + +===== genbg ====================================================== + +Usage: genbg [-c -ugs -vq -lzF] [-Z#] [-D#] [-A] [-d#|-d#:#] [-D#|-D#:#] n1 n2 + [mine[:maxe]] [res/mod] [file] + +Find all bicoloured graphs of a specified class. + + n1 : the number of vertices in the first class + n2 : the number of vertices in the second class +mine:maxe : a range for the number of edges + #:0 means ’# or more’ except in the case 0:0 + res/mod : only generate subset res out of subsets 0..mod-1 + file : the name of the output file (default stdout) + -c : only write connected graphs + -z : all the vertices in the second class must have + different neighbourhoods + -F : the vertices in the second class must have at least two + + + neighbours of degree at least 2 + -L : there is no vertex in the first class whose removal leaves + the vertices in the second class unreachable from each other + -Y# : two vertices in the second class must have at least # common nbrs + -Z# : two vertices in the second class must have at most # common nbrs + -A : no vertex in the second class has a neighbourhood which is a + subset of another vertex’s neighbourhood in the second class + -D# : specify an upper bound for the maximum degree + Example: -D6. You can also give separate maxima for the + two parts, for example: -D5:6 + -d# : specify a lower bound for the minimum degree. + Again, you can specify it separately for the two parts: -d1:2 + -g : use graph6 format for output (default) + -s : use sparse6 format for output + -a : use Greechie diagram format for output + -u : do not output any graphs, just generate and count them + -v : display counts by number of edges to stderr + -l : canonically label output graphs (using the 2-part colouring) + + -q : suppress auxiliary output + + See program text for much more information. + +===== geng ====================================================== + +Usage: geng [-cCmtfkbd#D#] [-kTSPF] [-uygsnh] [-lvq] + [-x#X#] n [mine[:maxe]] [res/mod] [file] + +Generate all graphs of a specified class. + + n : the number of vertices +mine:maxe : a range for the number of edges + #:0 means ’# or more’ except in the case 0:0 + res/mod : only generate subset res out of subsets 0..mod-1 (see below) + + -c : only write connected graphs + -C : only write biconnected graphs + -t : only generate triangle-free graphs + -f : only generate 4-cycle-free graphs + -p : only generate 5-cycle-free graphs + -k : only generate K4-free graphs + -T : only generate chordal graphs + -S : only generate split graphs + -P : only generate perfect graphs + -F : only generate claw-free graphs + -b : only generate bipartite graphs + (-t, -f and -b can be used in any combination) +The combination -bT gives bipartite graphs with no + + + induced cycles longer than 4-cycles. + -m : save memory at the expense of time (only makes a + difference in the absence of -b, -t, -f and n <= 28). + -d# : a lower bound for the minimum degree + -D# : an upper bound for the maximum degree + -v : display counts by number of edges + -l : canonically label output graphs + + -u : do not output any graphs, just generate and count them + -g : use graph6 output (default) + -s : use sparse6 output + -h : for graph6 or sparse6 format, write a header too + + -q : suppress auxiliary output (except from -v) + +res/mod splitting is controlled by two parameters -X# and -x# whose default +values are displayed when splitting is used. Increasing them will make the +division into parts more even at the expense of more overhead, but you must +use the same values for all parts. Splitting obeys the laws of modular +arithmetic, for example 3/7 is the union of 3/14 and 10/14, but when +subdividing like this you must manually provide the same -X and -x values +to the smaller parts. + +===== genktreeg ====================================================== + +Usage: genktreeg [-k#] [-lq] n [res/mod] [file] + +Generate all k-trees on n vertices. + + n : the number of vertices + -k# : the value of k (default 2) + res/mod : only generate subset res out of subsets 0..mod-1 + + -l : canonically label output graphs + + -u : do not output any graphs, just generate and count them + -g : use graph6 output (default) + -s : use sparse6 output + -h : write a header (only with -g or -s) + + -q : suppress auxiliary output + + + + +===== genposetg ====================================================== + +Usage: genposetg n [o|t] [q] [m x y] where n <= 16 is the number of points + Generate the Hasse diagrams of the posets with n points + o causes digraph6 output in arbitrary order to be written to stdout + t causes digraph6 output in topological order to be written to stdout + c restricts the program to connected posets + q supresses statistics except for the final count + m x y with 0 <= x < y divides the generation + into y parts and writes only part x. + +===== genquarticg ====================================================== + +Usage: genquarticg [-ugs -h -c -l] n [res/mod] [file] + + generate all non-isomorphic quartic graphs of a given order + + n : the number of the vertices + file : the name of the output file (default stdout) + -u : do not output any graphs, just generate and count them + -g : use graph6 format for output (default) + -s : use sparse6 format for output + -h write a header (only with -g or -s). + -c : only write connected graphs + -C : only write biconnected graphs + res/mod : only generate subset res out of subsets 0..mod-1 + -l : canonically label output graphs. + +===== genrang ====================================================== + +Usage: genrang [-P#|-P#/#|-e#|-r#|-R#|-d#] [-M#] [-l#] [-m#] [-t] [-T] [-a] + [-s|-g|-z] [-S#] [-q] n|n1,n2 num [outfile] + +Generate random graphs. + n : number of vertices + n1,n2 : number of vertices (bipartite graph) + num : number of graphs + + A bipartite variant is only available if specified below. + + -s : Write in sparse6 format (default) + -g : Write in graph6 format + -z : Make random digraphs and write in digraph6 format + -P#/# : Give edge probability; -P# means -P1/#. + Bipartite version available. + -e# : Give the number of edges + Bipartite version available. + -r# : Make regular of specified degree + + + -d# : Make regular of specified degree (pseudorandom) + With -z, #-in #-out digraph without loops + Bipartite version: this is the degree on the first side. + -M# : In conjunction with -d, make the distribution more uniform + by running a Markov chain for #*n steps starting at the + pseudorandom graph. + -R# : Make regular of specified degree but output + as vertex count, edge count, then list of edges + -l# : Maximum loop multiplicity (default 0) + -m# : Maximum multiplicity of non-loop edge (default and minimum 1) + -t : Make a random spanning tree of a complete graph + or complete bipartite graph + -T : Make a random tournament (implies -z) + -a : Make invariant under a random permutation + -S# : Specify random generator seed (default nondeterministic) + -q : suppress auxiliary output + +===== genspecialg ====================================================== + +Usage: genspecialg [-s|-g|-z|-d|-v] [-q] [graph options]... [outfile] + +Generate special graphs. + # : size parameter called n in the descriptions + + -s : Write in sparse6 format (default) + -g : Write in graph6 format + -z : Make digraph versions and write in digraph6 format + -d : Write in dreadnaut format (can be used with -z) + -v : For each graph, report the size to stderr + -q : Suppress summary + + If defined, the digraph version is shown in : + -p# : path on n vertices + -c# : cycle on n vertices + -e# : empty graph on n vertices + -k# : complete graph on n vertices + -b#,#[,#] : complete bipartite graph r> on n vertices + minus a matching of given size if present + -m#,#... : multipartite graph + -a# : antiprism on 2n + -l# : moebius ladder with # vertices + -D#,# : de Bruijn graph . D(m,t) has order m^t + -w# : wheel with # spokes + -f# : flower snark on 4n vertices + -L# : triangular graph, the linegraph of K_n + -P#,# : generalized Petersen graph; usual one is -P5,2 + -Q# -Q#,# : hypercube on 2^n vertices. Q(n,t) has vertices {0,1}^n + and edges for hamming distance t. t=1 is default. + + + -A# : connected antiregular graph on n vertices + -J#,# : Johnson graph J(n,k), args are n and k + -K#,# -K#,#,# : Generalized Kneser graph. K(n,k,t) is graph of k-subsets + of an n-set whose intersection is t. Default for t is 0. + -C#,#... : circulant graph; first arg is the number of vertices + -T#,#... : theta graph Theta(#,#,...), give path lengths + -G#,#... : grid, use negative values for open directions + -Y# : Paley graph or digraph, depending on size. Nondeterministic. + -X# : produce a named graph, # can be an index or a partial name. + Use genspecialg --Xhelp for a list. + + Any number of graphs can be generated at once. + +Arguments for genspecialg -X. Either the index or an unambigous prefix of + the case-insensitive name can be used. The -g switch is ignored. +index graph name vertices degree edges girth +150 ArmaniosWellsGraph 32 5 80 5 + 1 Balaban10CageGraph 70 3 105 10 + 2 Balaban11CageGraph 112 3 168 11 + 3 BarnetteBosakLederbergGraph 38 3 57 4 + 4 BerlekampVanLintSeidelGraph 243 22 2673 3 + 5 BidiakisCube 12 3 18 4 + 6 BiggsSmithGraph 102 3 153 9 + 7 BlanusaSnark1 18 3 27 5 + 8 BlanusaSnark2 18 3 27 5 + 9 BrinkmannGraph 21 4 42 5 + 10 BrouwerHaemersGraph 81 20 810 3 + 11 Cage39Graph1 58 3 87 9 + 12 Cage39Graph10 58 3 87 9 + 13 Cage39Graph11 58 3 87 9 + 14 Cage39Graph12 58 3 87 9 + 15 Cage39Graph13 58 3 87 9 + 16 Cage39Graph14 58 3 87 9 + 17 Cage39Graph15 58 3 87 9 + 18 Cage39Graph16 58 3 87 9 + 19 Cage39Graph17 58 3 87 9 + 20 Cage39Graph18 58 3 87 9 + 21 Cage39Graph2 58 3 87 9 + 22 Cage39Graph3 58 3 87 9 + 23 Cage39Graph4 58 3 87 9 + 24 Cage39Graph5 58 3 87 9 + 25 Cage39Graph6 58 3 87 9 + 26 Cage39Graph7 58 3 87 9 + 27 Cage39Graph8 58 3 87 9 + 28 Cage39Graph9 58 3 87 9 + 29 Cage46Graph 30 4 60 6 + 30 Cage47Graph 67 4 134 7 + 31 Cage48Graph 80 4 160 8 + + + 32 Cage58Graph 170 5 425 8 +127 Cage66Graph 62 6 186 6 + 33 Cage68Graph 312 6 936 8 + 34 Cage76Graph 90 7 315 6 + 35 CameronGraph 231 30 3465 3 +128 ChangGraph1 28 12 168 3 +129 ChangGraph2 28 12 168 3 + 36 ChangGraph3 28 12 168 3 + 37 ChvatalGraph 12 4 24 4 + 38 ClebschGraph 16 5 40 4 +151 ConwaySmithGraph 63 10 315 3 +154 CoolsaetDegraerGraph 42 13 273 3 + 39 CoxeterGraph 28 3 42 7 + 40 DejterGraph 112 6 336 4 +153 DelsarteGraph 243 110 13365 3 + 41 DesarguesGraph 20 3 30 6 + 42 DodecahedronGraph 20 3 30 5 +130 DoobGraph1 64 9 288 3 +131 DoobGraph2 256 12 1536 3 +152 DoroGraph 68 12 408 3 + 43 DoubleStarSnark 30 3 45 6 + 44 DoyleGraph 27 4 54 5 + 45 DuererGraph 12 3 18 4 + 46 DyckGraph 32 3 48 6 + 47 EllinghamHorton54 54 3 81 6 + 48 EllinghamHorton78 78 3 117 6 + 49 ErreraGraph 17 5-6 45 3 + 50 FolkmanGraph 20 4 40 4 + 51 FosterCageGraph 30 5 75 5 + 52 FosterGraph 90 3 135 10 + 53 FranklinGraph 12 3 18 4 + 54 FruchtGraph 12 3 18 3 + 55 GeneralizedHexagonGraph 126 3 189 12 +134 GeneralizedOctagon45 45 4 90 3 +132 GeneralizedOctagon160 160 6 480 3 +133 GeneralizedOctagon425 425 8 1700 3 + 56 GeorgesGraph 50 3 75 6 + 57 GewirtzGraph 56 10 280 4 +156 GoethalsSeidelGraph 105 32 1680 3 + 58 GoldnerHararyGraph 11 3-8 27 3 + 59 GolombGraph 10 3-6 18 3 + 60 GossetGraph 56 27 756 3 +135 GrassmannGraph1 35 18 315 3 +136 GrassmannGraph2 155 42 3255 3 +137 GrassmannGraph3 651 90 29295 3 + 61 GrayGraph 54 3 81 8 + 62 GreatRhombicosidodecahedralGraph 120 3 180 4 + 63 GreatRhombicuboctahedralGraph 48 3 72 4 + + + 64 GrinbergGraph 46 3 69 5 +155 GritsenkoGraph 65 32 1040 3 + 65 GroetzschGraph 11 3-5 20 4 +138 HallGraph 65 10 325 3 + 66 HallJankoGraph 100 36 1800 3 +139 HallJankoNearOctagon 315 10 1575 3 + 67 HarborthGraph 52 4 104 3 + 68 HarriesGraph 70 3 105 10 + 69 HarriesWongGraph 70 3 105 10 + 70 HatzelGraph 57 3-4 88 4 + 71 HeawoodGraph 14 3 21 6 + 72 HerschelGraph 11 3-4 18 4 + 73 HigmanSimsGraph 100 22 1100 4 + 74 HoffmanGraph 16 4 32 4 + 75 HoffmanSingletonGraph 50 7 175 5 + 76 HortonGraph92 92 3 138 6 + 77 HortonGraph96 96 3 144 6 + 78 IcosahedronGraph 12 5 30 3 + 79 IcosidodecahedralGraph 30 4 60 3 + 80 KittellGraph 23 5-7 63 3 + 81 KleinGraph 24 7 84 3 +149 KoolenRiebeekGraph.s6 486 45 10935 4 + 82 KrackhardtKiteGraph 10 1-6 18 3 +140 KummerGraph1 32 6 96 4 +141 KummerGraph2 36 6 108 4 +142 LeonardGraph 288 12 1728 4 + 83 LivingstoneGraph 266 11 1463 5 + 84 LjubljanaGraph 112 3 168 10 + 85 LoupekineSnark1 22 3 33 5 + 86 LoupekineSnark2 22 3 33 5 + 87 M22Graph 77 16 616 4 + 88 MarkstroemGraph 24 3 36 3 + 89 McGeeGraph 24 3 36 7 + 90 McLaughlinGraph 275 112 15400 3 + 91 MeredithGraph 70 4 140 4 + 92 MeringerGraph 30 5 75 5 +143 Mesner-WittGraph 77 16 616 4 + 93 MirzakhaniGraph 63 4-42 183 3 + 94 MoebiusKantorGraph 16 3 24 6 + 95 NauruGraph 24 3 36 6 + 96 OctahedronGraph 6 4 12 3 + 97 PappusGraph 18 3 27 6 + 98 PerkelGraph 57 6 171 5 + 99 PetersenGraph 10 3 15 5 +100 PoussinGraph 15 4-6 39 3 +101 RobertsonGraph 19 4 38 5 +102 RobertsonWegnerGraph 30 5 75 5 +103 SchlaefliGraph 27 16 216 3 + + +104 ShrikhandeGraph 16 6 48 3 +125 Skeleton120cell 600 4 1200 5 +126 Skeleton600cell 120 12 720 3 +105 SmallRhombicosidodecahedralGraph 60 4 120 3 +106 SnubCubicalGraph 24 5 60 3 +107 SnubDodecahedralGraph 60 5 150 3 +108 SoccerBallGraph 60 3 90 5 +109 SousselierGraph 16 3-5 27 5 +110 SuzukiGraph 1782 416 370656 3 +111 SylvesterGraph 36 5 90 5 +144 SuetakeGraph 72 12 432 4 +112 SzekeresSnark 50 3 75 5 +145 TesseractGraph 16 4 32 4 +113 TietzeGraph 12 3 18 3 +114 TriangleReplacedCoxeterGraph 84 3 126 3 +115 TriangleReplacedPetersenGraph 30 3 45 3 +116 TruncatedDodecahedralGraph 60 3 90 3 +117 TruncatedIcosahedralGraph 60 3 90 5 +118 TruncatedOctahedralGraph 24 3 36 4 +119 TruncatedTetrahedralGraph 12 3 18 3 +120 Tutte8CageGraph 30 3 45 8 +146 Tutte12Cage 126 3 189 12 +147 VanLintSchrijverGraph 162 6 486 6 +121 WaltherGraph 25 1-3 31 4 +122 WellsGraph 32 5 80 5 +123 WienerArayaGraph 42 3-4 67 4 +124 WongGraph 30 5 75 5 +148 ZaraGraph 126 45 2835 3 + +===== gentourng ====================================================== + +Usage: gentourng [-cd#D#] [-ugsz] [-lq] n [res/mod] [file] + +Generate all tournaments of a specified class. + + n : the number of vertices + res/mod : only generate subset res out of subsets 0..mod-1 + + -c : only write strongly-connected tournaments + -d# : a lower bound for the minimum out-degree + -D# : a upper bound for the maximum out-degree + -l : canonically label output graphs + + -u : do not output any graphs, just generate and count them + -g : use graph6 output (lower triangle) + -s : use sparse6 output (lower triangle) + -z : use digraph6 output + -h : write a header (only with -g or -s) + + + Default output is upper triangle row-by-row in ascii + + -q : suppress auxiliary output + + See program text for much more information. + +===== gentreeg ====================================================== + +Usage: gentreeg [-D#] [-Z#:#] [-ulps] [-q] n|n1:n2 [res/mod] [file] + +Generate (unrooted) trees. + + n, n1:n2 : the number of vertices or a range + Outputs are in order of the number of vertices. + res/mod : only generate subset res out of subsets 0..mod-1 + + -D# : an upper bound for the maximum degree + -Z#:# : bounds for the diameter + + -s : use sparse6 output (default) + -p : write a parent array + -l : write a level array + -u : do not output any graphs, just generate and count them + + -q : suppress auxiliary output + + See program text for much more information. + +===== hamheuristic ====================================================== + +Usage: hamheuristic [-sgu] [-vq] [-V] [-L#] [-t#] [infile [outfile]] + +Apply a heuristic for finding hamiltonian cycles. + Output those which are unsuccessful. + + -s force output to sparse6 format + -g force output to graph6 format + If neither -s or -g are given, the output format is + determined by the header or, if there is none, by the + format of the first input graph. + -V Write those for which a cycle (path with -p) is found instead + -u Suppress output to outfile, give statistics instead. + + The output file will have a header if and only if the input file does. + + -p Be content with a hamiltonian path + -v Give a cycle or path if one is found. + -c If a cycle or path is found, perform an independent check of it. + + + -L# Limit number of sideways steps (default 1000+40*n) + -t# Try # times (default 1) + + -q suppress auxiliary information + +===== labelg ====================================================== + +Usage: labelg [-q] [-sgz | -C#W#] [-fxxx] [-S|-t] + [-i# -I#:# -K#] [infile [outfile]] + +Canonically label a file of graphs or digraphs. + + -s force output to sparse6 format + -g force output to graph6 format + -z force output to digraph6 format + If neither -s, -g or -z are given, the output format is + determined by the header or, if there is none, by the + format of the first input graph. As an exception, digraphs + are always written in digraph6 format. + -S Use sparse representation internally. + Note that this changes the canonical labelling. + Multiple edges are not supported. One loop per vertex is ok. + -t Use Traces. + Note that this changes the canonical labelling. + Multiple edges and loops are not supported, nor invariants. + + -C# Make an invariant in 0..#-1 and output the number of graphs + with each value of the invariant. Don’t write graphs unless + -W too. + -W# (requires -C) Output the graphs with this invariant value, + in their original labelling. Don’t write the table. + + The output file will have a header if and only if the input file does. + + -fxxx Specify a partition of the vertex set. xxx is any + string of ASCII characters except nul. This string is + considered extended to infinity on the right with the + character ’z’. The sequence ’x^N’, where x is a character and N is + a number, is equivalent to writing ’x’ N times. One character is + associated with each vertex, in the order given. The labelling + used obeys these rules: + (1) the new order of the vertices is such that the associated + characters are in ASCII ascending order + (2) if two graphs are labelled using the same string xxx, + the output graphs are identical iff there is an + associated-character-preserving isomorphism between them. + If a leading ’-’ is used, as in -f-xxx, the characters are + assigned to the vertices starting at the last vertex, and + + + the new order of the vertices respects decreasing ASCII order. + + -i# select an invariant (1 = twopaths, 2 = adjtriang(K), 3 = triples, + 4 = quadruples, 5 = celltrips, 6 = cellquads, 7 = cellquins, + 8 = distances(K), 9 = indsets(K), 10 = cliques(K), 11 = cellcliq(K), + 12 = cellind(K), 13 = adjacencies, 14 = cellfano, 15 = cellfano2, + 16 = refinvar(K)) + -I#:# select mininvarlevel and maxinvarlevel (default 1:1) + -K# select invararg (default 3) + + -q suppress auxiliary information + +===== linegraphg ====================================================== + +Usage: linegraphg [-t] [-q] [infile [outfile]] + +Take the linegraphs of a file of graphs. + Input graphs with no edges produce only a warning message. + + The output file has a header if and only if the input file does. + + -t make the total graph + -q Suppress auxiliary information. + +===== listg ====================================================== + +Usage: listg [-fp#:#l#o#Ftq] [-a|-A|-c|-d|-e|-H|-M|-W|-L|S|-s|-b|-G|-y|-Yxxx] + [infile [outfile]] + +Write graphs in human-readable format. + + -f : assume inputs have same size (only used from a file + and only if -p is given) + -p#, -p#:#, -p#-# : only display one graph or a sequence of + graphs. The first graph is number 1. A second number + which is empty or zero means infinity. + This option won’t work for incremental input. + -a : write as adjacency matrix, not as list of adjacencies + -A : same as -a with a space between entries + -l# : specify screen width limit (default 78, 0 means no limit) + This is not currently implemented with -a or -A. + -o# : specify number of first vertex (default is 0). + -d : write output to satisfy dreadnaut + -c : write ascii form with minimal line-breaks + -e : write a list of edges, preceded by the order and the + number of edges + -M : write in Magma format + -m : write in Mathematica format + + + -W : write matrix in Maple format + -H : write in HCP operations research format + -T : write in the edge-list format needed by the program tutte + -L : (only with -M or -W) write Laplacian rather than adjacency matrix + -S : (only with -M or -W) write signless Laplacian not adjacency matrix + -b : write in DIMACS format + -G : write in GRAPE format + -y : write in dot file format + -Yxxx : extra dotty commands for dot files (arg continues to end of param) + -t : write upper triangle only (affects -a, -A, -d and default) + -s : write only the numbers of vertices and edges + -F : write a form-feed after each graph except the last + -q : suppress auxiliary output + + -a, -A, -c, -d, -M, -W, -H and -e are incompatible. + +===== multig ====================================================== + +Usage: multig [-q] [-V] [-u|-T|-G|-A|-B] [-e#|-e#:#] + [-m#] [-f#] [-D#|-r#|-l#] [infile [outfile]] + +Read undirected loop-free graphs and replace their edges with multiple + edges in all possible ways (multiplicity at least 1). + Isomorphic multigraphs derived from the same input are suppressed. + If the input graphs are non-isomorphic then the output graphs are also. + + -e# | -e#:# specify a value or range of the total number of edges + counting multiplicities + -m# maximum edge multiplicity (minimum is 1) + -D# upper bound on maximum degree + -r# make regular of specified degree (incompatible with -l, -D, -e) + -l# make regular multigraphs with multiloops, degree # + (incompatible with -r, -D, -e) + -f# Use the group that fixes the first # vertices setwise + -V read the T format as produced by vcolg and obey the vertex colours + in computing the automorphism group. If -T or -G is used as the + output format, a list of the input colours is included. + Either -l, -r, -D, -e or -m with a finite maximum must be given + -T use a simple text output format (nv ne {v1 v2 mult}) + -G like -T but includes group size as third item (if less than 10^10) + The group size does not include exchange of isolated vertices. + -A write as the upper triangle of an adjacency matrix, row by row, + including the diagonal, and preceded by the number of vertices + -B write as an integer matrix preceded by the number of rows and + number of columns, where -f determines the number of rows + -u no output, just count them + -q suppress auxiliary information + + + +===== nbrhoodg ====================================================== + +Usage: nbrhoodg [-lq] [-c|-C] [-d#|d#:#] [-v#|-v#:#] [infile [outfile]] + +Extract neighbourhoods of vertices of a graph. + + The output file has a header if and only if the input file does. + No isomorph reduction is done. No null graphs are written. + + -l Canonically label outputs (default is same labelling as input) + -C Extract closed neighbourhoods instead. + -c Extract non-neighbourhoods instead. + -D# Extract neighbourhoods out to distance # (implies -C) + -d# -d#:# Only include vertices with original degree in the given range + -v# -v#:# Only include vertices with these vertex numbers (first is 0). + No empty graphs are output. + For digraphs, out-degree and out-neighbourhoods are used. + -q Suppress auxiliary information + +===== newedgeg ====================================================== + +Usage: newedgeg [-lq] [infile [outfile]] + +For each pair of non-adjacent edges, output the graph obtained + by subdividing the edges and joining the new vertices. + + The output file has a header if and only if the input file does. + + -l Canonically label outputs + -q Suppress auxiliary information + +===== NRswitchg ====================================================== + +Usage: NRswitchg [-lq] [infile [outfile]] + +For each v, complement the edges from N(v) to V(G)-N(v)-v. + + The output file has a header if and only if the input file does. + + -l Canonically label outputs. + -q Suppress auxiliary information. + + + + +===== pickg ====================================================== + +Usage: [pickg|countg] [-fp#:#q -V -X] [--keys] [-constraints -v] [ifile [ofile]] + +countg : Count graphs according to their properties. + pickg : Select graphs according to their properties. + + ifile, ofile : Input and output files. + ’-’ and missing names imply stdin and stdout. + + Miscellaneous switches: + -p# -p#:# Specify range of input lines (first is 1) + May fail if input is incremental. + -f With -p, assume input lines of fixed length + (only used with a file in graph6/digraph6 format) + -v Negate all constraints (but not -p) + -X Reverse selection (but -p still observed) + -V List properties of every input matching constraints. + -l Put a blank line whenever the first parameter changes, + if there are at least two parameters. + -1 Write output as lines of numbers separated by spaces, + with 0/1 for boolean and both endpoints of ranges given + separately even if they are the same, and the count at + the end of the line. Also, no total is written. + -2 The same as -1 but counts are not written. + -9 Flush the output after each graph (expensive if many graphs) + -q Suppress informative output. + + Constraints: + Numerical constraints (shown here with following #) can take + a single integer value, or a range like #:#, #:, or :#. Each + can also be preceded by ’~’, which negates it. (For example, + -~D2:4 will match any maximum degree which is _not_ 2, 3, or 4.) + Constraints are applied to all input graphs, and only those + which match all constraints are counted or selected. + + -n# number of vertices -e# number of edges + -ee# number of non-edges (including loops for digraphs) + -L# number of loops -C strongly connected + -LL# number of 2-cycles -cc# number of components + -d# minimum (out-)degree -D# maximum (out-)degree + -m# vertices of min (out-)degree -M# vertices of max (out-)degree + -u# minimum (in-)degree -U# maximum (in-)degree + -s# vertices of min (in-)degree -S# vertices of max (in-)degree + -r regular -b bipartite + -z# radius -Z# diameter + -g# girth (0=acyclic) -Y# total number of cycles + -h# maximum independent set -k# maximum clique + + + -T# number of triangles -K# number of maximal cliques + -TT# number independent 3-sets -P# number of 5-cycles + -B# smallest possible first side of a bipartition (0 if nonbipartite) + -H# number of induced cycles -W# number of 4-cycles + -E Eulerian (all degrees are even, connectivity not required) + -a# group size -o# orbits -F# fixed points -t vertex-transitive + -O# number of orbits of edges -OO# number of orbits of arcs + -tt# 1 = edge transitive, 2 = arc transitive, 0 = neither + -c# connectivity (2 means 2 or more). + -kk# #-tree, otherwise 0. The complete graph K_n is tabulated as + an n-tree, but matches either n-1 or n, + -i# min common nbrs of adjacent vertices; -ii# maximum + -j# min common nbrs of non-adjacent vertices; -jj# maximum + -x# number of sources -xx# number of sinks + -WW# number of diamonds -HH# number of hexagons + -N# chromatic number (limited to WORDSIZE colours) + -NN# chromatic index (limited to max degree WORDSIZE-1) + -A# class (chromatic index - maximum degree + 1) + -G# connectivity -GG# edge connectivity + + Sort keys: + Counts are made for all graphs passing the constraints. Counts + are given separately for each combination of values occurring for + the properties listed as sort keys. A sort key is introduced by + ’--’ and uses one of the letters known as constraints. These can + be combined: --n --e --r is the same as --ne --r and --ner. + The order of sort keys is significant. + A comma can be used as a separator. + The sort key ’:’ has a special purpose: the values of sort keys + following ’:’ are given as ranges rather than creating a separate + line for each value. For example --e:zZ will give the ranges of + radius and diameter that occur for each number of edges. + The output format matches the input, except that sparse6 is used + to output an incremental graph whose predecessor is not output. + + Some sort keys have boolean variants with parameters: + --N# #-colourable (i.e. chromatic number <= #) + --NN# #-edge colourable + --G# #-connected (i.e. connectivity >= #) + --GG# #-edge connected + +===== planarg ====================================================== + +Usage: planarg [-v] [-nVq] [-p|-u] [infile [outfile]] + +For each input, write to output if planar. + + The output file has a header if and only if the input file does. + + + -v Write non-planar graphs instead of planar graphs + -V Write report on every input + -u Don’t write anything, just count + -p Write in planar_code if planar (without -p, same format as input) + -P Like -p but big-endian (same for <= 255 vertices) + -k Follow each non-planar output with an obstruction in sparse6 + format (implies -v, incompatible with -p) + -n Suppress checking of the result + -q Suppress auxiliary information + + This program permits multiple edges and loops + +===== productg ====================================================== + +Usage: productg [-u|-c|-l|-L|-k|-t|-a#] [infile [outfile]] + +Read two graphs in graph6/sparse6 format and write their product + in sparse6 or dreadnaut format. + -d : Dreadnaut format (default is sparse6) + + -c : Cartesian product + -l : Lexicographic product (G1[G2]) + -L : Lexicographic product (G2[G1]) + -t : Tensor (Kronecker, categorical, direct) product + -k : Complete (strong, normal) product + -a# : general case (argument is a 3-digit octal number) + Add these values giving the condition for an edge: + Code: 400 200 100 040 020 010 004 002 001 + Graph1: same same same adj adj adj nonadj nonadj nonadj + Graph2: same adj nonadj same adj nonadj same adj nonadj + + -u : Disjoint union + + -q : Suppress informative output + +===== ranlabg ====================================================== + +Usage: ranlabg [-q] [-f#] [-m#] [-S#] [infile [outfile]] + +Randomly relabel graphs. + + The output file has a header if and only if the input file does. + Each graph is written in the same format as it is read. + + -f# Don’t relabel the first # vertices. + -m# Output # randomly labelled copies of each input (default 1). + -S# Set random number seed (taken from clock otherwise). + + + -q Suppress auxiliary information. + +===== ransubg ====================================================== + +Usage: ransubg [-lq] [-P#|-P#/#] [-z] [-o] [-m#] [-S#] [infile [outfile]] + +Extract random graph/digraphs of a file of graphs. + + The output file has a header if and only if the input file does. + The output format is defined by the header or first graph, + but is always digraph6 if -z is used. + + -z Treat the input as a directed graph + -o Treat the input as a directed graph and output an oriented graph + -P# or -P#/# Specify a probability p. -P# is the same as -P1/# + -m# Make this many outputs for each input (default 1) + -l Canonically label outputs. + -S# Set seed for random numbers (default nondeterministic) + + Usually each edge is kept with probability p. + In the case of -o, each edge in one direction only is kept + with probability p. For edges in both directions, with probability p + keep one direction randomly chosen and with probability 1-p delete + both directions. Thus -oP1 will make a random orientation of an + undirected graph. + -q Suppress auxiliary information. + +===== shortg ====================================================== + +Usage: shortg [-qvkdu] [-i# -I#:# -K#] [-fxxx] [-S|-t] [-Tdir] [-Z#] [infile [outfile]] + + Remove isomorphs from a file of graphs. + + If outfile is omitted, it is taken to be the same as infile + If both infile and outfile are omitted, input will be taken + from stdin and written to stdout + + The output file has a header if and only if the input file does. + + -s force output to sparse6 format + -g force output to graph6 format + -z force output to digraph6 format + If none of -s, -z, -g are given, the output format is determined + by the header or, if there is none, by the format of the first + input graph. The output format determines the sorting order too. + As an exception, digraphs are always written in digraph6 format. + -S Use sparse representation internally. Note that this changes the + + + canonical labelling. + Multiple edges are not supported. One loop per vertex is ok. +-t Use Traces. + Note that this changes the canonical labelling. + Multiple edges,loops, directed edges are not supported, + nor invariants. + +-k output graphs have the same labelling and format as the inputs. + Without -k, output graphs have canonical labelling. + -s, -g, -z are ineffective if -k is given. + +-v write to stderr a list of which input graphs correspond to which + output graphs. The input and output graphs are both numbered + beginning at 1. A line like + 23 : 30 154 78 + means that inputs 30, 154 and 78 were isomorphic, and produced + output 23. + +-d include in the output only those inputs which are isomorphic + to another input. If -k is specified, all such inputs are + included in their original labelling. Without -k, only one + member of each nontrivial isomorphism class is written, + with canonical labelling. + +-fxxx Specify a partition of the vertex set. xxx is any + string of ASCII characters except nul. This string is + considered extended to infinity on the right with the + character ’z’. The sequence ’x^N’, where x is a character and N is + a number, is equivalent to writing ’x’ N times. One character is + associated with each vertex, in the order given. The labelling + used obeys these rules: + (1) the new order of the vertices is such that the associated + characters are in ASCII ascending order + (2) if two graphs are labelled using the same string xxx, + the output graphs are identical iff there is an + associated-character-preserving isomorphism between them. + If a leading ’-’ is used, as in -f-xxx, the characters are + assigned to the vertices starting at the last vertex, and + the new order of the vertices respects decreasing ASCII order. + +-i# select an invariant (1 = twopaths, 2 = adjtriang(K), 3 = triples, + 4 = quadruples, 5 = celltrips, 6 = cellquads, 7 = cellquins, + 8 = distances(K), 9 = indsets(K), 10 = cliques(K), 11 = cellcliq(K), + 12 = cellind(K), 13 = adjacencies, 14 = cellfano, 15 = cellfano2, + 16 = refinvar(K)) +-I#:# select mininvarlevel and maxinvarlevel (default 1:1) +-K# select invararg (default 3) + + + + -u Write no output, just report how many graphs it would have output. + In this case, outfile is not permitted. + -Tdir Specify that directory "dir" will be used for temporary disk + space by the sort subprocess. The default is usually /tmp. + -Z# Specify memory for sorting (number followed by %,K,M, or G) + -q Suppress auxiliary output + +===== showg ====================================================== + +Usage: showg [-p#:#l#o#Ftq] [-a|-A|-c|-d|-e] [infile [outfile]] + +Write graphs in human-readable format. + + infile is the input file in graph6, sparse6 or digraph6 format + This program does not support incremental sparse6 files; use listg. + outfile is the output file + Defaults are standard input and standard output. + + -p#, -p#:#, -p#-# : only display one graph or a sequence of + graphs. The first graph is number 1. A second number + which is empty or zero means infinity. + + -a : write the adjacency matrix + -A : same as -a with a space between entries + -d : write output to satisfy dreadnaut + -c : write compact dreadnaut form with minimal line-breaks + -e : write a list of edges, preceded by the order and the + number of edges + + -o# : specify number of first vertex (default is 0) + -t : write upper triangle only (affects -a, -A, -d and default) + -F : write a form-feed after each graph except the last + -l# : specify screen width limit (default 78, 0 means no limit) + This is not currently implemented with -a or -A. + -q : suppress auxiliary output + + -a, -A, -c, -d and -e are incompatible. + +===== subdivideg ====================================================== + +Usage: subdivideg [-k#] [-i] [-q] [infile [outfile]] + +Make the subdivision graphs of a file of graphs, or the inverse operation. + -k# Subdivide each edge by # new vertices (default 1) + -i Perform homeomorphic series reduction + For undirected graphs, repeatedly replace x--y--z by x--z if + x,y are not adjacent and y has no other neighbours. + For digraphs, repeatedly replace x->y->z by x->z if x,z are + + + distinct, x->z is not present, and y has no other neighbours. + + The output file has a header if and only if the input file does. + + -q Suppress auxiliary information. + +===== twohamg ====================================================== + +Usage: twohamg [-sgvq] [-L#] [infile [outfile]] + +Partition quartic graphs into two hamiltonian cycles. + Output those which cannot be partitioned. + + -s force output to sparse6 format + -g force output to graph6 format + If neither -s or -g are given, the output format is + determined by the header or, if there is none, by the + format of the first input graph. Also see -S. + + The output file will have a header if and only if the input file does. + + -p Read a cubic graph and use its prism. Vertex i of the input becomes + vertices 2*i,2*i+1 in the prism. + -x Test for decompositions using each 2-path + -X As -x but only output if two 2-paths are missed at some vertex + -y Test for decompositions using each non-triangular 3-path + -t# With -x and -X, consider only paths with center # + With -y, consider only paths starting at # + -Y With -p, only consider paths whose central edge is vertical + -v Give a partition for those graphs who have one and a message + for those which don’t. With -x, list exceptional 2-paths. + -L# Limit to 1000*# iterations; write with message if timeout. + Graphs that time out are written to the output. + + -q suppress auxiliary information + +===== underlyingg ====================================================== + +Usage: underlyingg [-q] [infile [outfile]] + +Take the underlying undirected graphs of a file of graphs. + + The output file has no header. + Undirected graphs are passed through without change, while + Underlying graphs of digraphs are written in sparse6 format. + + -q Suppress auxiliary information. + + + +===== uniqg ====================================================== + +Usage: uniqg [-q] [-xFILE] [-Xfile] [-hFILE] [-fxxx] [-u|-S|-t] + [-c] [-k] [-i# -I#:# -K#] [infile [outfile]] + +Remove duplicates from a file of graphs or digraphs. + The SHA256 cryptographic hash function is used for comparisons + + -S Use sparse representation internally. + Note that this changes the canonical labelling. + Multiple edges are not supported. One loop per vertex is ok. + -t Use Traces. + + -u No output, just count + -H Write hash codes, not graphs (note: binary output) + -k Write the input graph exactly, not a canonical graph + -c Assume graphs from infile are canonically labelled already + + -xFILE Read a file of graphs and exclude them from the output + -XFILE Like -xFILE but assume they are already canonically labelled + -hFILE Read a file of hash codes and exclude them from the output + -F Flush output for each new graph (expensive if there are many) + + -fxxx Specify a partition of the vertex set. xxx is any + string of ASCII characters except nul. This string is + considered extended to infinity on the right with the + character ’z’. The sequence ’x^N’, where x is a character and N is + a number, is equivalent to writing ’x’ N times. One character is + associated with each vertex, in the order given. The labelling + used obeys these rules: + (1) the new order of the vertices is such that the associated + characters are in ASCII ascending order + (2) if two graphs are labelled using the same string xxx, + the output graphs are identical iff there is an + associated-character-preserving isomorphism between them. + If a leading ’-’ is used, as in -f-xxx, the characters are + assigned to the vertices starting at the last vertex, and + the new order of the vertices respects decreasing ASCII order. + + -y Write a 256-bit cryptographic hashcode to stderr. This depends on + the set of isomorphism classes but not their order. It also + depends on -i, -I, -K, -S, -t and -c. + + -i# select an invariant (1 = twopaths, 2 = adjtriang(K), 3 = triples, + 4 = quadruples, 5 = celltrips, 6 = cellquads, 7 = cellquins, + 8 = distances(K), 9 = indsets(K), 10 = cliques(K), 11 = cellcliq(K), + 12 = cellind(K), 13 = adjacencies, 14 = cellfano, 15 = cellfano2, + 16 = refinvar(K)) + + + -I#:# select mininvarlevel and maxinvarlevel (default 1:1) + -K# select invararg (default 3) + + -q suppress auxiliary information + +===== vcolg ====================================================== + +Usage: vcolg [-q] [-u|-T|-o|-O] [-e#|-e#:#] [-m#] [-c#,..,#] [-f#] [infile [outfile]] + + Read graphs or digraphs and colour their vertices in + all possible ways with colours 0,1,2,... . + Isomorphic graphs derived from the same input are suppressed. + If the input graphs are non-isomorphic then the output graphs are also. + + -e# | -e#:# specify a value or range of the total value of the colours + -m# number of available colours (default 2 if -c not given) + -c#,..,# specify the maximum number of vertices of each colour + The total must at least equal the number of vertices in the input. + -d#,..,# minimum vertex degree for each colour (out-degree for digraphs) + -D#,..,# maximum vertex degree for each colour (out-degree for digraphs) + -d and -D can have fewer colours than -m/-c but not more + -f# Use the group that fixes the first # vertices setwise + -T Use a simple text output format (nv ne {col} {v1 v2}) + -o Use sparse6 (undirected) or digraph6 (directed) for output, + provided m=2 and the inputs have no loops. + -O Same as -o but use loops for weight 0, not weight 1 + -u no output, just count them + -q suppress auxiliary information + +===== watercluster2 ====================================================== + +Usage: watercluster2 [ix] [oy] [m] [T] [C] [B] [Z] [S] + Read undirected graphs and orient them in various ways. + +The option ix restricts the maximum indegree to x. +The option oy restricts the maximum outdegree to y. +The default maximum in- and out-degrees are unlimited. +T means: Output directed graphs in T-code -- for details see header +B means: Output directed graphs in binary code -- for details see header +Z means: Output directed graphs in digraph6 code +C means: Do really construct all the directed graphs in memory, + but don’t output them (default) +S means that for each edge only one direction must be chosen -- not both. +Default is that both are allowed + -- so the edge a-b can become a->b AND b->a in the same output graph. +m means: read multicode instead of g6 code + + + + diff --git a/apn/lean/docs/normaliz/LICENSE b/apn/lean/docs/normaliz/LICENSE new file mode 100644 index 00000000..33214776 --- /dev/null +++ b/apn/lean/docs/normaliz/LICENSE @@ -0,0 +1,682 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. + + + +As an exception, when this program is distributed through (i) the App Store +by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or (iii) Google Play +by Google Inc., then that store may impose any digital rights management, +device limits and/or redistribution restrictions that are required by its +terms of service. diff --git a/apn/lean/docs/normaliz/normaliz-manual.txt b/apn/lean/docs/normaliz/normaliz-manual.txt new file mode 100644 index 00000000..6eccbe48 --- /dev/null +++ b/apn/lean/docs/normaliz/normaliz-manual.txt @@ -0,0 +1,3604 @@ + + +2. Discrete convex geometry by examples +2.1. Terminology +For the precise interpretation of parts of the Normaliz output some terminology is necessary, +but this section can be skipped at first reading, and the user can come back to it when it +becomes necessary. We will give less formal descriptions along the way. The following applies +to rational polyhedra. Algebraic polyhedra are discussed in Section 8. +As pointed out in the introduction, Normaliz “computes” intersections P ∩ L where P is a +rational polyhedron in Rd and L is an affine sublattice of Zd . It proceeds as follows: + (1) If the input is inhomogeneous, then it is homogenized by introducing a homogenizing + coordinate: the polyhedron P is replaced by the cone C(P): it is the closure of R+ (P × + {1}) in Rd+1 . Similarly L is replaced by L + e = Z(L × {1}). In the homogeneous case in + which P is a cone and L is a subgroup of Zd , we set C(P) = P and Le = L. + (2) The computations take place in the efficient lattice + e ∩ RC(P). + E=L + + where RC(P) is the linear subspace generated by C(P). The internal coordinates are + chosen with respect to a basis of E. The efficient cone is + + C = R+ (C(P) ∩ E). + + (3) Inhomogeneous computations are truncated using the dehomogenization (defined im- + plicitly or explicitly). + (4) The final step is the conversion to the original coordinates. Note that we must use the + coordinates of Rd+1 if homogenization has been necessary, simply because some output + vectors may be non-integral otherwise. +Normaliz computes inequalities, equations and congruences defining E and C. The output +contains only those constraints that are really needed. They must always be used jointly: the +equations and congruences define E, and the equations and inequalities define C. Altogether +they define the monoid M = C ∩ E. In the homogeneous case this is the monoid to be com- +puted. In the inhomogeneous case we must intersect M with the dehomogenizing hyperplane +to obtain P ∩ L. +In this section, only pointed cones (and polyhedra with vertices) will be discussed. Nonpointed +cones will be addressed in Section 7.13. + + +2.2. Practical preparations +You may find it comfortable to run Normaliz via the GUI jNormaliz [4]. In the Normaliz +directory open jNormaliz by clicking jNormaliz.jar in the appropriate way. (We assume that +Java is installed on your machine.) In the jNormaliz file dialogue choose one of the input files + + + + Figure 1: jNormaliz + + +in the subdirectory example, say small.in, and press Run. In the console window you can +watch Normaliz at work. Finally inspect the output window for the results. +The menus and dialogues of jNormaliz are self explanatory, but you can also consult the +documentation [4] via the help menu. +Remark The jNormaliz drop down menus do presently not cover all options of Normaliz. But +since all computation goals and algorithmic variants can be set in the input file, there is no +real restriction in using jNormaliz. The only option not reachable by jNormaliz is the output +directory (see Section 6.7). +Moreover, one can, and often will, run Normaliz from the command line. This is fully ex- +plained in Section 6. At this point it is enough to call Normaliz by typing + normaliz -c + +where denotes for the project to be computed. Normaliz will load the file .in. +The option -c makes Normaliz to write a progress report on the terminal. Normaliz writes its +results to .out. +Note that you may have to prefix normaliz by a path name, and must contain a +path to the input file if it is not in the current directory. Suppose the Normaliz directory is the +current directory and we are using a Linux or Mac system. Then + ./normaliz -c example/small + +will run small.in from the directory example. On Windows we must change this to + .\normaliz -c example\small + +The commands given above will run Normaliz with the at most 8 parallel threads. For the very +small examples in this tutorial you may want to add -x=1 to suppress parallelization. For large +examples, you can increase the number of parallel threads by -x= where is the number + + + +of threads that you want to suggest. See Section 6.3. +As long as you don’t specify a computation goal on the command line or in the input file, +Normaliz will use the default computation goals: + +HilbertBasis +HilbertSeries +ClassGroup + +The computation of the Hilbert series requires the explicit or implicit definition of a grading. +Normaliz does only complain that a computation goal cannot be reached if the goal has been +set explicitly. For example, if you say HilbertSeries and there is no grading, an exception +will be thrown and Normaliz terminates, but an output file with the already computed data will +be written. +Note that the spacing in the output files may have changed over time and that not all these +changes may have made their way into this manual. +Normaliz will always print the results that are obtained on the way to the computation goals +and do not require extra effort. +Appendix B helps you to read the console output that you have demanded by the option -c. + + +2.3. A cone in dimension 2 +We want to investigate the cone C = R+ (2, 1) + R+ (1, 3) ⊂ R2 : + + + + + +This cone is defined in the input file 2cone.in: + amb_space 2 + cone 2 + 1 3 + 2 1 + +The input tells Normaliz that the ambient space is R2 , and then a cone with 2 generators is +defined, namely the cone C from above. +The figure indicates the Hilbert basis, and this is our first computation goal. + + + +If you prefer to consider the columns of a matrix as input vectors (or have a matrix in this +format from another system) you can use the input + amb_space 2 + cone transpose 2 + 1 2 + 3 1 + +Note that the number 2 following transpose is now the number of columns. Later on we will +also show the use of formatted matrices. + +2.3.1. The Hilbert basis + +In order to compute the Hilbert basis, we run Normaliz from jNormaliz or by + ./normaliz -c example/2cone + +and inspect the output file: + 4 Hilbert basis elements + 2 extreme rays + 2 support hyperplanes + +Self explanatory so far. + embedding dimension = 2 + rank = 2 (maximal) + external index = 1 + internal index = 5 + original monoid is not integrally closed in chosen lattice + +The embedding dimension is the dimension of the space in which the computation is done. +The rank is the rank of the lattice E (notation as in Section 2.1). In fact, in our example E = Z2 , +and therefore has rank 2. +For subgroups G ⊂ U ⊂ Zd we denote the order of the torsion subgroup of U/G by the index +of G in U. The external index is the index of the lattice E in Zd . In our case E = Zd , and +therefore the external index is 1. Note: the external index is 1 exactly when E is a direct +summand of Zd . +For this example and many others the original monoid is well defined: the generators of the +cone used as input are contained in E. (This need not be the case if E is a proper sublattice of +Zd , and we let the original monoid be undefined in inhomogeneous computations.) Let G be +the subgroup generated by the original monoid. The internal index is the index of G in E. +The original monoid is integrally closed if and only if the it contains the Hilbert basis, and this +is evidently false for our example. We go on. + size of triangulation = 1 + resulting sum of |det|s = 5 + + + + +The primal algorithm of Normaliz relies on a (partial) triangulation. In our case the triangula- +tion consists of a single simplicial cone, and (the absolute value of) its determinant is 5. + No implicit grading found + +If you do not define a grading explicitly, Normaliz tries to find one itself: the grading is defined +if and only if there is a linear form γ on E under which all extreme rays of the efficient cone +C have value 1, and if so, γ is the implicit grading. Such does not exist in our case. +The last information before we come to the vector lists: + rank of class group = 0 + finite cyclic summands: + 5: 1 + +The class group of the monoid M has rank 0, in other words, it is finite. It has one finite cyclic +summand of order 5. +This is the first instance of a multiset of integers displayed as a sequence of pairs + : +Such an entry says: the multiset contains the number with multiplicity . +Now we look at the vector lists (typeset in two columns to save space): + 4 Hilbert basis elements: 2 extreme rays: + 1 1 1 3 + 1 2 2 1 + 1 3 + 2 1 2 support hyperplanes: + -1 2 + 3 -1 + +The support hyperplanes are given by the linear forms (or inner normal vectors): + + −x1 + 2x2 ≥ 0, + 3x1 − x2 ≥ 0. + +If the order is not fixed for some reason, Normaliz sorts vector lists as follows: (1) by degree +if a grading exists and the application makes sense, (2) lexicographically. + + +2.3.2. The cone by inequalities + +Instead by generators, we can define the cone by the inequalities just computed (2cone_ineq.in). +We use this example to show the input of a formatted matrix: + amb_space auto + inequalities + [[-1 2] [3 -1]] + + + + +A matrix of input type inequalities contains homogeneous inequalities. Normaliz can deter- +mine the dimension of the ambient space from the formatted matrix. Therefore we can declare +the ambient space as being “auto determined” (but amb_space 2 is not forbidden). +We get the same result as with 2cone.in except that the data depending on the original monoid +cannot be computed: the internal index and the information on the original monoid are missing +since there is no original monoid. + +2.3.3. The interior + +Now we want to compute the lattice points in the interior of our cone. If the cone C is given +by the inequalities λi (x) ≥ 0 (within aff(C)), then the interior is given by the inequalities +λi (x) > 0. Since we are interested in lattice points, we work with the inequalities λi (x) ≥ 1. +The input file 2cone_int.in says + amb_space 2 + strict_inequalities 2 + -1 2 + 3 -1 + +The strict inequalities encode the conditions + −x1 + 2x2 ≥ 1, + 3x1 − x2 ≥ 1. +This is our first example of inhomogeneous input. +Note that the strict inequalities do not define the interior of the cone as a point set. They define +a (closed) polyhedron with the same lattice points as the interior. + + + + + + +Alternatively we could use the following two equivalent input files, in a more intuitive nota- +tion: + amb_space 2 + constraints 2 + -1 2 > 0 + 3 -1 > 0 + + + + + amb_space 2 + constraints 2 + -1 2 >= 1 + 3 -1 >= 1 + + +There is an even more intuitive way to type the input file using symbolic constraints that we +will introduce in Section 2.6.2. +Normaliz homogenizes inhomogeneous computations by introducing an auxiliary homogeniz- +ing coordinate xd+1 . The polyhedron is obtained by intersecting the homogenized cone with +the hyperplane xd+1 = 1. The recession cone is the intersection with the hyperplane xd+1 = 0. +The recession monoid is the monoid of lattice points in the recession cone, and the set of lattice +points in the polyhedron is represented by its system of module generators over the recession +monoid. +Note that the homogenizing coordinate serves as the denominator for rational vectors. In our +example the recession cone is our old friend that we have already computed, and therefore we +need not comment on it. + 2 module generators + 4 Hilbert basis elements of recession monoid + 1 vertices of polyhedron + 2 extreme rays of recession cone + 3 support hyperplanes of polyhedron (homogenized) + + + embedding dimension = 3 + affine dimension of the polyhedron = 2 (maximal) + rank of recession monoid = 2 + + +The only surprise may be the embedding dimension: Normaliz always takes the dimension +of the space in which the computation is done. It is the number of components of the output +vectors. Because of the homogenization it has increased by 1. + size of triangulation = 1 + resulting sum of |det|s = 25 + +In this case the homogenized cone has stayed simplicial, but the determinant has changed. + dehomogenization: + 0 0 1 + +The dehomogenization is the linear form δ on the homogenized space that defines the hyper- +planes from which we get the polyhedron and the recession cone by the equations δ (x) = 1 +and δ (x) = 0, respectively. It is listed since one can also work with a user defined dehomoge- +nization. + module rank = 1 + +This is the rank of the module of lattice points in the polyhedron over the recession monoid. + + + +In our case the module is an ideal, and so the rank is 1. +The output of inhomogeneous computations is always given in homogenized form. The last +coordinate is the value of the dehomogenization on the listed vectors, 1 on the module gener- +ators, 0 on the vectors in the recession monoid: + 2 module generators: 4 Hilbert basis elements of recession monoid: + 1 1 1 1 1 0 + 1 2 1 1 2 0 + 1 3 0 + 2 1 0 + +The module generators are (1, 1) and (1, 2). + 1 vertices of polyhedron: + 3 4 5 + +Indeed, the polyhedron has a single vertex, namely (3/5, 4/5). + 2 extreme rays of recession cone: 3 support hyperplanes of polyhedron (homogenized): + 1 3 0 -1 2 -1 + 2 1 0 0 0 1 + 3 -1 -1 + +Two support hyperplanes are exactly those that we have used to define the polyhedron – and +it has only 2. But Normaliz always outputs the support hyperplanes that are needed for the +cone that one obtains by homogenizing the polyhedron, as indicated by “homogenized”. The +homogenizing variable is always ≥ 0. In this case the support hyperplane (0, 0, 1) is essential +for the description of the cone. Note that it need not always appear. + + +2.4. A lattice polytope +The file polytope.in contains + + amb_space 4 + polytope 4 + 0 0 0 + 2 0 0 + 0 3 0 + 0 0 5 + +This is a good place to mention that Normaliz also accepts matrices (and vectors) in sparse +format: + amb_space 4 + polytope 4 sparse + ; + 1:2; + + + + + 2:3; + 3:5; + + +Each input row, concluded by ;, lists the indices and the corresponding nonzero values in that +row of the matrix. +The Ehrhart monoid of the integral polytope with the 4 vertices + + (0, 0, 0) , (2, 0, 0) , (0, 3, 0) and (0, 0, 5) + +in R3 is to be computed. The generators of the Ehrhart monoid are obtained by attaching a +further coordinate 1 to the vertices, and this explains amb_space 4. In fact, the input type +polytope is not only a convenient version of + + cone 4 + 0 0 0 1 + 2 0 0 1 + 0 3 0 1 + 0 0 5 1 + +It also sets the he grading to be the last coordinate. See 4.12 below for general information on +gradings. +Running normaliz produces the file polytope.out: + 19 Hilbert basis elements + 18 lattice points in polytope (Hilbert basis elements of degree 1) + 4 extreme rays + 4 support hyperplanes + + + embedding dimension = 4 + rank = 4 (maximal) + external index = 1 + internal index = 30 + original monoid is not integrally closed in chosen lattice + +Perhaps a surprise: the lattice points of the polytope do not yield all Hilbert basis elements. + size of triangulation = 1 + resulting sum of |det|s = 30 + +Nothing really new so far. The grading appears in the output file: + grading: + 0 0 0 1 + + + degrees of extreme rays: + 1: 4 + +Again we encounter the notation : : we have 4 extreme rays, all of degree 1. + + + + Hilbert basis elements are not of degree 1 + +We knew this already: the polytope is not integrally closed as defined in [11]. Now we see the +enumerative data defined by the grading: + multiplicity = 30 + + + Hilbert series: + 1 14 15 + denominator with 4 factors: + 1: 4 + + + degree of Hilbert Series as rational function = -2 + + + Hilbert polynomial: + 1 4 8 5 + with common denominator = 1 + +The polytope has Z3 -normalized volume 30 as indicated by the multiplicity (see Section 7.1.1 +for a discussion of volumes and multiplicities). The Hilbert (or Ehrhart) function counts the +lattice points in kP, k ∈ Z+ . The corresponding generating function is a rational function H(t). +For our polytope it is + 1 + 14t + 15t 2 + . + (1 − t)4 +The denominator is given in multiset notation: 1: 4 say that the factor (1 − t 1 ) occurs with +multiplicity 4. +The Ehrhart polynomial (again we use a more general term in the output file) of the polytope +is + p(k) = 1 + 4k + 8k2 + 5k3 . +In our case it has integral coefficients, a rare exception. Therefore one usually needs a denom- +inator. +Everything that follows has already been explained. + rank of class group = 0 + finite cyclic summands: + 30: 1 + + + *********************************************************************** + + 18 lattice points in polytope (Hilbert basis elements of degree 1): + 0 0 0 1 + ... + 2 0 0 1 + + + + + 1 further Hilbert basis elements of higher degree: + 1 2 4 2 + + + 4 extreme rays: 4 support hyperplanes: + 0 0 0 1 -15 -10 -6 30 + 0 0 5 1 0 0 1 0 + 0 3 0 1 0 1 0 0 + 2 0 0 1 1 0 0 0 + +The support hyperplanes give us a description of the polytope by inequalities: it is the solution +of the system of the 4 inequalities + + x3 ≥ 0 , x2 ≥ 0 , x1 ≥ 0 and 15x1 + 10x2 + 6x3 ≤ 30 . + +2.4.1. Only the lattice points + +Suppose we want to compute only the lattice points in our polytope. In the language of +graded monoids these are the degree 1 elements, and so we add Deg1Elements to our input file +(polytope_deg1.in): + amb_space 4 + polytope 4 + 0 0 0 + 2 0 0 + 0 3 0 + 0 0 5 + Deg1Elements + /* This is our first explicit computation goal*/ + +We have used this opportunity to include a comment in the input file. The computation of +lattice points in a polytope will be taken up again in Sections 2.13 and 7.2. +We lose all information on the Hilbert series, and from the Hilbert basis we only retain the +degree 1 elements. + + +2.5. A rational polytope +The type polytope can (now) be used for rational polytopes as well. + + + + +We want to investigate the Ehrhart series of the triangle P with vertices + (1/2, 1/2), (−1/3, −1/3), (1/4, −1/2). +For this example the procedure above yields the input file rational.in: + amb_space 3 + polytope 3 + 1/2 1/2 + -1/3 -1/3 + 1/4 -1/2 + HilbertSeries + + +From the output file we only list the data of the Ehrhart series. + multiplicity = 5/8 + multiplicity (float) = 0.625 + + + Hilbert series: + 1 0 0 3 2 -1 2 2 1 1 1 1 2 + denominator with 3 factors: + 1: 1 2: 1 12: 1 + + + degree of Hilbert Series as rational function = -3 + + + Hilbert series with cyclotomic denominator: + -1 -1 -1 -3 -4 -3 -2 + cyclotomic denominator: + 1: 3 2: 2 3: 1 4: 1 + + + Hilbert quasi-polynomial of period 12: + 0: 48 28 15 7: 23 22 15 + 1: 11 22 15 8: 16 28 15 + 2: -20 28 15 9: 27 22 15 + 3: 39 22 15 10: -4 28 15 + 4: 32 28 15 11: 7 22 15 + 5: -5 22 15 with common denominator = 48 + 6: 12 28 15 + +The multiplicity is a rational number. Since in dimension 2 the normalized area (of full- +dimensional polytopes) is twice the Euclidean area, we see that P has Euclidean area 5/16. +If the multiplicity is not integral, we also print it in floating point format, This is certainly +superfluous for a fraction like 5/8, but very handy if the numerator and the denominator have +many digits. +Unlike in the case of a lattice polytope, there is no canonical choice of the denominator of the +Ehrhart series. Normaliz gives it in 2 forms. In the first form the numerator polynomial is + 1 + 3t 3 + 2t 4 − t 5 + 2t 6 + 2t 7 + t 8 + t 9 + t 10 + t 11 + 2t 12 + + + +and the denominator is + (1 − t)(1 − t 2 )(1 − t 12 ). +As a rational function, H(t) has degree −3. This implies that 3P is the smallest integral +multiple of P that contains a lattice point in its interior. +Normaliz gives also a representation as a quotient of coprime polynomials with the denomi- +nator factored into cyclotomic polynomials. In this case we have + + 1 + t + t 2 + t 3 + 4t 4 + 3t 5 + 2t 6 + H(t) = − + ζ13 ζ22 ζ3 ζ4 + +where ζi is the i-th cyclotomic polynomial (ζ1 = t − 1, ζ2 = t + 1, ζ3 = t 2 +t + 1, ζ4 = t 2 + 1). +Normaliz transforms the representation with cyclotomic denominator into one with denomi- +nator of type (1 − t e1 ) · · · (1 − t er ), r = rank, by choosing er as the least common multiple of +all the orders of the cyclotomic polynomials appearing, er−1 as the lcm of those orders that +have multiplicity ≥ 2 etc. +There are other ways to form a suitable denominator with 3 factors 1 − t e , for example g(t) = +(1 − t 2 )(1 − t 3 )(1 − t 4 ) = −ζ13 ζ22 ζ3 ζ4 . Of course, g(t) is the optimal choice in this case. +However, P is a simplex, and in general such optimal choice may not exist. We will explain +the reason for our standardization below. +Let p(k) be the number of lattice points in kP. Then p(k) is a quasipolynomial: + + p(k) = p0 (k) + p1 (k)k + · · · + pr−1 (k)kr−1 , + +where the coefficients depend on k, but only to the extent that they are periodic of a certain +period π ∈ N. In our case π = 12 (the lcm of the orders of the cyclotomic polynomials). +The table giving the quasipolynomial is to be read as follows: The first column denotes the +residue class j modulo the period and the corresponding line lists the coefficients pi ( j) in +ascending order of i, multiplied by the common denominator. So + 7 5 + p(k) = 1 + k + k2 , k ≡ 0 (12), + 12 16 +etc. The leading coefficient is the same for all residue classes and equals the Euclidean volume +(in this case). +Our choice of denominator for the Hilbert series is motivated by the following fact: ei is the +common period of the coefficients pr−i , . . . , pr−1 . The user should prove this fact or at least +verify it by several examples. +Especially in the case of a simplex the representation of the Hilbert series shown so far may +not be the expected one. In fact, there is a representation in which the exponents of t in the +denominator are the degrees of the integral extreme generators. So one would expect the +denominator to be (1 − t 2 )(1 − t 3 )(1 − t 4 ) in our case. The generalization to the nonsimplicial +case uses the degrees of a homogeneous system of parameters (see [11, p. 200]). Normaliz +can compute such a denominator if the computation goal + + + +HSOP +is set (rationalHSOP.in): + Hilbert series (HSOP): + 1 1 1 3 4 3 2 + denominator with 3 factors: + 2: 1 3: 1 4: 1 + +Note that the degrees of the elements in a homogeneous system of parameters are by no means +unique and that there is no optimal choice in general. To find a suitable sequence of degrees +Normaliz must compute the face lattice of the cone to some extent. Therefore be careful not +to ask for HSOP if the cone has many support hyperplanes. + + +2.5.1. The series with vertices? + +It is tempting to define the polytope by the input type vertices. This choice makes the com- +putation inhomogeneous, a mode that is mainly meant for (potentially) unbounded polyhedra. +But it can be used for polytopes as well, and with this input type you can compute all of the data +that we have seen above. You must ask for the EhrhartSeries instead of the HilbertSeries. +The file rational_inhom.in is + amb_space 2 + vertices 3 + 1/2 1/2 1 + -1/3 -1/3 1 + 1/4 -1/2 1 + EhrhartSeries + +Nevertheless, there is also use for HilbertSeries in the inhomogeneous case. But then the +grading must be defined on the affine space of the polytope (and not on the cone over the +polytope). See Sections 7.1 and 7.10.2. + + +2.5.2. The rational polytope by inequalities + +We extract the support hyperplanes of our polytope from the output file and use them as input +(poly_ineq.in): + amb_space 3 + inequalities 3 + -8 2 3 + 1 -1 0 + 2 7 3 + grading + unit_vector 3 + HilbertSeries + + + + +At this point we have to help Normaliz because it has no way to guess that we want to inves- +tigate the polytope defined by the inequalities and the choice x3 = 1. This is achieved by the +specification of the grading that maps every vector to its third coordinate. +This is the first time that we used the shortcut unit_vector which represents the n-th unit +vector en ∈ Rd and is only allowed for input types which require a single vector. +These data tell us that the polytope, as a subset of R2 , is defined by the inequalities + + −8x1 + 2x2 + 3 ≥ 0, + x1 − x2 + 0 ≥ 0, + 2x1 + 7x2 + 3 ≥ 0. + +These inequalities are inhomogeneous, but we are using the homogeneous input type inequalities +which amounts to introducing the grading variable x3 as explained above. +The inequalities as written above look somewhat artificial. It is certainly more natural to write +them in the form + + 8x1 − 2x2 ≤ 3, + x1 − x2 ≥ 0, + 2x1 + 7x2 ≥ −3. + +and for the direct transformation into Normaliz input we have introduced the type hom_constraints. +The prefix hom indicates that we want homogeneous inequalities whereas plain constraints +that we have already seen in Section 2.3.3 gives inhomogeneous inequalities. The file poly_hom_const.in +contains + amb_space 3 + hom_constraints 3 + 8 -2 <= 3 + 1 -1 >= 0 + 2 7 >= -3 + grading + unit_vector 3 + HilbertSeries + +You can of course also switch to inhomogeneous input using inhom_inequalities or constraints +in the same way as polytope can be replaced by vertices. + + +2.6. Magic squares +Suppose that you are interested in the following type of “square” + + x1 x2 x3 + x4 x5 x6 + x7 x8 x9 + + + +and the problem is to find nonnegative values for x1 , . . . , x9 such that the 3 numbers in all rows, +all columns, and both diagonals sum to the same constant M . Sometimes such squares are +called magic and M is the magic constant. This leads to a linear system of equations + + x1 + x2 + x3 = x4 + x5 + x6 ; + x1 + x2 + x3 = x7 + x8 + x9 ; + x1 + x2 + x3 = x1 + x4 + x7 ; + x1 + x2 + x3 = x2 + x5 + x8 ; + x1 + x2 + x3 = x3 + x6 + x9 ; + x1 + x2 + x3 = x1 + x5 + x9 ; + x1 + x2 + x3 = x3 + x5 + x7 . + + +This system is encoded in the file 3x3magic.in: + amb_space 9 + equations 7 + 1 1 1 -1 -1 -1 0 0 0 + 1 1 1 0 0 0 -1 -1 -1 + 0 1 1 -1 0 0 -1 0 0 + 1 0 1 0 -1 0 0 -1 0 + 1 1 0 0 0 -1 0 0 -1 + 0 1 1 0 -1 0 0 0 -1 + 1 1 0 0 -1 0 -1 0 0 + grading + sparse 1:1 2:1 3:1; + +The input type equations represents homogeneous equations. The first equation reads + + x1 + x2 + x3 − x4 − x5 − x6 = 0, + +and the other equations are to be interpreted analogously. The magic constant is a natural +choice for the grading. It is given in sparse form, equivalent to the dense form + grading + 1 1 1 0 0 0 0 0 0 + +It seems that we have forgotten to define the cone. This may indeed be the case, but doesn’t +matter: if there is no input type that defines a cone, Normaliz chooses the positive orthant, and +this is exactly what we want in this case. +The output file contains the following: + 5 Hilbert basis elements + 5 lattice points in polytope (Hilbert basis elements of degree 1) + 4 extreme rays + 4 support hyperplanes + + + + + embedding dimension = 9 + rank = 3 + external index = 1 + + + size of triangulation = 2 + resulting sum of |det|s = 4 + + + grading: + 1 1 1 0 0 0 0 0 0 + with denominator = 3 + + +The input degree is the magic constant. However, as the denominator 3 shows, the magic +constant is always divisible by 3, and therefore the effective degree is M /3. This degree is +used for the multiplicity, the Hilbert series, and the Hilbert basis elements of degree 1, and +other date depending on the degree. +By introducing the grading denominator, Normaliz has changed the grading defined by you, +and you may not like this. There is a way out: add the option NoGradingDenom. We will +discuss the consequences below. + degrees of extreme rays: + 1: 4 + + + Hilbert basis elements are of degree 1 + +This was not to be expected (and is no longer true for 4 × 4 squares). + multiplicity = 4 + + + Hilbert series: + 1 2 1 + denominator with 3 factors: + 1: 3 + + + degree of Hilbert Series as rational function = -1 + + + Hilbert polynomial: + 1 2 2 + with common denominator = 1 + +The Hilbert series is + 1 + 2t + t 2 + . + (1 − t)3 +The Hilbert polynomial is + P(k) = 1 + 2k + 2k2 , +and after substituting M /3 for k we obtain the number of magic squares of magic constant + + + +M , provided 3 divides M . (If 3 ∤ M , there is no magic square of magic constant M .) + rank of class group = 1 + finite cyclic summands: + 2: 2 + +So the class group is Z ⊕ (Z/2Z)2 . + 5 lattice points in polytope (Hilbert basis elements of degree 1): + 0 2 1 2 1 0 1 0 2 + 1 0 2 2 1 0 0 2 1 + 1 1 1 1 1 1 1 1 1 + 1 2 0 0 1 2 2 0 1 + 2 0 1 0 1 2 1 2 0 + + + 0 further Hilbert basis elements of higher degree: + +The 5 elements of the Hilbert basis represent the magic squares + + 2 0 1 1 0 2 1 1 1 1 2 0 0 2 1 + 0 1 2 2 1 0 1 1 1 0 1 2 2 1 0 + 1 2 0 0 2 1 1 1 1 2 0 1 1 0 2 + +All other solutions are linear combinations of these squares with nonnegative integer coeffi- +cients. One of these 5 squares is clearly in the interior: + 4 extreme rays: 4 support hyperplanes: + 0 2 1 2 1 0 1 0 2 -2 -1 0 0 4 0 0 0 0 + 1 0 2 2 1 0 0 2 1 0 -1 0 0 2 0 0 0 0 + 1 2 0 0 1 2 2 0 1 0 1 0 0 0 0 0 0 0 + 2 0 1 0 1 2 1 2 0 2 1 0 0 -2 0 0 0 0 + +These 4 support hyperplanes cut out the cone generated by the magic squares from the linear +subspace they generate. Only one is reproduced as a sign inequality. This is due to the fact that +the linear subspace has submaximal dimension and there is no unique lifting of linear forms +to the full space. + 6 equations: 3 basis elements of generated lattice: + 1 0 0 0 0 1 -2 -1 1 1 0 -1 -2 0 2 1 0 -1 + 0 1 0 0 0 1 -2 0 0 0 1 -1 -1 0 1 1 -1 0 + 0 0 1 0 0 1 -1 -1 0 0 0 3 4 1 -2 -1 2 2 + 0 0 0 1 0 -1 2 0 -2 + 0 0 0 0 1 -1 1 0 -1 + 0 0 0 0 0 3 -4 -1 2 + +So one of our equations has turned out to be superfluous (why?). Note that also the equations +are not reproduced exactly. Finally, Normaliz lists a basis of the efficient lattice E generated +by the magic squares. + + + + +Note that the equations and the lattice basis are not uniquely determined. We transform their +matrices into reduced row echelon form to force unique output files. + + +2.6.1. Blocking the grading denominator + +As mentioned above, one can block the grading denominator and force Normaliz to use the +input grading. For the magic squares we augment the input file as follows (3x3magicNGD.in): + amb_space 9 + equations 7 + 1 1 1 -1 -1 -1 0 0 0 + ... + 1 1 0 0 -1 0 -1 0 0 + grading + sparse 1:1 2:1 3:1; + NoGradingDenom + +The consequences: + grading: + 1 1 1 0 0 0 0 0 0 + + + degrees of extreme rays: + 3: 4 + + + multiplicity = 4/9 + multiplicity (float) = 0.444444444444 + + + Hilbert series: + 1 0 0 2 0 0 1 + denominator with 3 factors: + 3: 3 + + + degree of Hilbert Series as rational function = -3 + + + The numerator of the Hilbert series is symmetric. + + + Hilbert series with cyclotomic denominator: + -1 0 0 -2 0 0 -1 + cyclotomic denominator: + 1: 3 3: 3 + + + Hilbert quasi-polynomial of period 3: + 0: 9 6 2 + 1: 0 0 0 + 2: 0 0 0 + with common denominator = 9 + + + + + rank of class group = 1 + finite cyclic summands: + 2: 2 + + + *********************************************************************** + + 0 lattice points in polytope (Hilbert basis elements of degree 1): + +It is easy to relate the data with the grading denominator to those without. You must decide +yourself what you prefer. One aspect is whether one prefers intrinsic data (with grading de- +nominator) to extrinsic ones that depend on the embedding (without the grading denominator). +We will discuss the topic again in Section 7.1. + +2.6.2. With even corners + +We change our definition of magic square by requiring that the entries in the 4 corners are all +even. Then we have to augment the input file by the following (3x3magiceven.in): + congruences 4 sparse + 1:1 10:2; + 3:1 10:2; + 7:1 10:2; + 9:1 10:2; + +This sparse form is equivalent to the dense form + congruences 4 + 1 0 0 0 0 0 0 0 0 2 + 0 0 1 0 0 0 0 0 0 2 + 0 0 0 0 0 0 1 0 0 2 + 0 0 0 0 0 0 0 0 1 2 + +The first 9 entries in each row represent the coefficients of the coordinates in the homogeneous +congruences, and the last is the modulus: + + x1 ≡ 0 mod 2 + +is the first congruence etc. +We could also define these congruences as symbolic constraints: + constraints 4 symbolic + x[1] ~ 0(2); + x[3] ~ 0(2); + x[7] ~ 0(2); + x[9] ~ 0(2); + +The output changes accordingly: + + + + 9 Hilbert basis elements + 0 lattice points in polytope (Hilbert basis elements of degree 1) + 4 extreme rays + 4 support hyperplanes + + + embedding dimension = 9 + rank = 3 + external index = 4 + + + size of triangulation = 2 + resulting sum of |det|s = 8 + + + grading: + 1 1 1 0 0 0 0 0 0 + with denominator = 3 + + + degrees of extreme rays: + 2: 4 + + + multiplicity = 1 + + + Hilbert series: + 1 -1 3 1 + denominator with 3 factors: + 1: 1 2: 2 + + + degree of Hilbert Series as rational function = -2 + + + Hilbert series with cyclotomic denominator: + -1 1 -3 -1 + cyclotomic denominator: + 1: 3 2: 2 + + + Hilbert quasi-polynomial of period 2: + 0: 2 2 1 + 1: -1 0 1 + with common denominator = 2 + + +After the extensive discussion in Section 2.5 it should be easy for you to write down the Hilbert +series and the Hilbert quasipolynomial. (But keep in mind that the grading has a denominator.) + rank of class group = 1 + finite cyclic summands: + 4: 2 + + + *********************************************************************** + + + + + 0 lattice points in polytope (Hilbert basis elements of degree 1): + + + 9 further Hilbert basis elements of higher degree: + ... + + + 4 extreme rays: + 0 4 2 4 2 0 2 0 4 + 2 0 4 4 2 0 0 4 2 + 2 4 0 0 2 4 4 0 2 + 4 0 2 0 2 4 2 4 0 + +We have listed the extreme rays since they have changed after the introduction of the congru- +ences, although the cone has not changed. The reason is that Normaliz always chooses the +extreme rays from the efficient lattice E. + 4 support hyperplanes: + ... + + + 6 equations: + ... 3 basis elements of generated lattice: + 1 0 -1 -2 0 2 1 0 -1 + 2 congruences: 0 1 -1 -1 0 1 1 -1 0 + 1 0 0 0 0 0 0 0 0 2 0 0 3 4 1 -2 -1 2 2 + 0 1 0 0 1 0 0 0 0 2 + +The rank of the lattice has of course not changed, but after the introduction of the congruences +the basis has changed. + +2.6.3. The lattice as input + +It is possible to define the lattice by generators. We demonstrate this for the magic squares +with even corners. The lattice has just been computed (3x3magiceven_lat.in): + amb_space 9 + lattice 3 + 0 1 2 3 1 -1 0 1 2 + 2 -1 2 1 1 1 0 3 0 + 0 3 0 1 1 1 2 -1 2 + grading + 1 1 1 0 0 0 0 0 0 + + +It produces the same output as the version starting from equations and congruences. +lattice has a variant that takes the saturation of the sublattice generated by the input vectors +(3x3magic_sat.in): + amb_space 9 + + + + + saturation 3 + 0 1 2 3 1 -1 0 1 2 + 2 -1 2 1 1 1 0 3 0 + 0 3 0 1 1 1 2 -1 2 + grading + 1 1 1 0 0 0 0 0 0 + + +Clearly, we remove the congruences by this choice and arrive at the output of 3x3magic.in. + + +2.7. Decomposition in a numerical semigroup +Let S = ⟨6, 10, 15⟩, the numerical semigroup generated by 6, 10, 15. How can 97 be written as +a sum in the generators? +In other words: we want to find all nonnegative integral solutions to the equation + 6x1 + 10x2 + 15x3 = 97. + +Input (NumSemi.in): + + amb_space 3 + constraints 1 symbolic + 6x[1] + 10x[2] + 15x[3] = 97; + + +The equation cuts out a triangle from the positive orthant. +The set of solutions is a module over the monoid M of solutions of the homogeneous equation +6x1 + 10x2 + 15x3 = 0. So M = 0 in this case. + 6 lattice points in polytope (module generators): + 2 1 5 1 + 2 4 3 1 + 2 7 1 1 + 7 1 3 1 + 7 4 1 1 + 12 1 1 1 + + + 0 Hilbert basis elements of recession monoid: + +The last line is as expected, and the 6 lattice points (or module generators) are the goal of the +computation. +Normaliz is smart enough to recognize that it must compute the lattice points in a polygon, +and does exactly this. You can recognize it in the console output: Normaliz 3.11.0 has used +the project-and-lift algorithm. We will discuss it further in Section 2.13 and Section 7.2.1. +For those who like to play: add the option --NoProjection to the command line. Then the +terminal output will change; Normaliz computes the lattice points as a truncated Hilbert basis +via a triangulation (only one simplicial cone in this case). + + + +2.8. A job for the dual algorithm +We increase the size of the magic squares to 5 × 5. Normaliz can do the same computation +as for 3 × 3 squares, but this will take some minutes. Suppose we are only interested in the +Hilbert basis, we should use the dual algorithm for this example. (The dual algorithm goes +back to Pottier [34].) The input file is 5x5dual.in: + amb_space 25 + equations 11 + 1 1 1 1 1 -1 -1 -1 -1 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 + ... + 1 1 1 1 0 0 0 0 -1 0 0 0 -1 0 0 0 -1 0 0 0 -1 0 0 0 0 + grading + 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 + HilbertBasis + + +The input file does not say anything about the dual algorithm mentioned in the section title. +With this input it is chosen automatically. See Section 7.5 for a discussion of when this +happens. But you can insist on the dual algorithm by adding DualMode to the input (or -d to +the command line). Or, if you want to compare it to the primal algorithm add PrimalMode (or +-P to the command line). +The Hilbert basis contains 4828 elements, too many to be listed here. +With the file 5x5.in you can compute the Hilbert basis and the Hilbert series, and the latter +with HSOP: + Hilbert series (HSOP): + 1 15 356 4692 36324 198467 ... 198467 36324 4692 356 15 1 + denominator with 15 factors: + 1: 5 2: 3 6: 2 12: 1 60: 2 420: 1 1260: 1 + + + degree of Hilbert Series as rational function = -5 + + + The numerator of the Hilbert Series is symmetric. + +In view of the length of the numerator of the Hilbert series it may be difficult to observe the +symmetry. So Normaliz does it for you. The symmetry shows that the monoid is Gorenstein, +but if you are only interested in the Gorenstein property, there is a much faster way to check it +(see Section 7.7). +The size 6 × 6 is out of reach for the Hilbert series, but the Hilbert basis can be computed (in +the automatically chosen dual mode). It takes some hours. + + + + +2.9. A dull polyhedron +We want to compute the polyhedron defined by the inequalities + + ξ2 ≥ −1/2, + ξ2 ≤ 3/2, + ξ2 ≤ ξ1 + 3/2. + +They are contained in the input file InhomIneq.in: + amb_space 2 + constraints 3 + 0 1 >= -1/2 + 0 1 <= 3/2 + -1 1 <= 3/2 + grading + unit_vector 1 + FVector + +The grading says that we want to count points by the first coordinate, namely along the green +lines: + + + + +It yields the output + 2 module generators + 1 Hilbert basis elements of recession monoid + 2 vertices of polyhedron + 1 extreme rays of recession cone + 3 support hyperplanes of polyhedron (homogenized) + + + f-vector: + 1 2 3 1 + +The empty set is the intersection of all facets, and this gives the first entry 1. Then we have 2 +vertices, 3 edges, and finally the full polyhedron. +The out put continues: + embedding dimension = 3 + affine dimension of the polyhedron = 2 (maximal) + rank of recession monoid = 1 + + + + + size of triangulation = 1 + resulting sum of |det|s = 8 + + + dehomogenization: + 0 0 1 + + + grading: + 1 0 0 + + +The interpretation of the grading requires some care in the inhomogeneous case. We have +extended the input grading vector by an entry 0 to match the embedding dimension. For the +computation of the degrees of lattice points in the ambient space you can either use only the +first 2 coordinates or take the full scalar product of the point in homogenized coordinates and +the extended grading vector. + module rank = 2 + multiplicity = 2 + + +The module rank is 2 in this case since we have two “layers” in the solution module that are +parallel to the recession monoid. This is of course also reflected in the Hilbert series. + Hilbert series: + 1 1 + denominator with 1 factors: + 1: 1 + + + shift = -1 + +We haven’t seen a shift yet. It is always printed (necessarily) if the Hilbert series does not start +in degree 0. In our case it starts in degree −1 as indicated by the shift −1. We thus get the +Hilbert series + t +t t −1 + 1 + t −1 = . + 1−t 1−t +Note: We used the opposite convention for the shift in Normaliz 2. +Note that the Hilbert (quasi)polynomial is always computed for the unshifted monoid defined +by the input data. (This was different in previous versions of Normaliz.) + degree of Hilbert Series as rational function = -1 + + + Hilbert polynomial: + 2 + with common denominator = 1 + + + *********************************************************************** + + 2 module generators: + -1 0 1 + + + + + 0 1 1 + + + 1 Hilbert basis elements of recession monoid: + 1 0 0 + + + 2 vertices of polyhedron: + -4 -1 2 + 0 3 2 + + + 1 extreme rays of recession cone: + 1 0 0 + + + 3 support hyperplanes of polyhedron (homogenized): + 0 -2 3 + 0 2 1 + 2 -2 3 + +The dual algorithm that was used in Section 2.8 can also be applied to inhomogeneous com- +putations. We would of course loose the Hilbert series. In certain cases it may be preferable +to suppress the computation of the vertices of the polyhedron if you are only interested in the +integer points; see Section 5.6. + + +2.9.1. Defining it by generators + +If the polyhedron is given by its vertices and the recession cone, we can define it by these data +(InhomIneq_gen.in): + amb_space 2 + vertices 2 + -4 -1 2 + 0 3 2 + cone 1 + 1 0 + grading + unit_vector 1 + +The output is identical to the version starting from the inequalities. + + +2.10. The Condorcet paradox +In social choice elections each of the k voters picks a linear preference order of the n candi- +dates. There are n! such orders. The election result is the vector (x1 , . . . , xN ), N = n!, in which +xi is the number of voters that have chosen the i-th preference order in, say, lexicographic enu- +meration of these orders. (Thus x1 + · · · + xN = k.) In the following we assume the impartial +anonymous culture according to which every election result has the same probability if the + + + +number of voters is fixed. + +We say that candidate A beats candidate B if the majority of the voters prefers A to B. As the +Marquis de Condorcet (and others) observed, “beats” is not transitive, and an election may +exhibit the Condorcet paradox: there is no Condorcet winner. (See [19] and the references +given there for more information.) +We want to find the probability for k → ∞ that there is a Condorcet winner for n = 4 candidates. +The event that A is the Condorcet winner can be expressed by linear inequalities on the election +outcome (a point in 24-space). The wanted probability is the lattice normalized volume of the +polytope cut out by the inequalities at k = 1. The file Condorcet.in: + amb_space 24 + inequalities 3 + 1 1 1 1 1 1 -1 -1 -1 -1 -1 -1 1 1 -1 -1 1 -1 1 1 -1 -1 1 -1 + 1 1 1 1 1 1 1 1 -1 -1 1 -1 -1 -1 -1 -1 -1 -1 1 1 1 -1 -1 -1 + 1 1 1 1 1 1 1 1 1 -1 -1 -1 1 1 1 -1 -1 -1 -1 -1 -1 -1 -1 -1 + nonnegative + total_degree + Multiplicity + + +The first inequality expresses that A beats B, the second and the third say that A beats C and +D. (So far we do not exclude ties, and they need not be excluded for probabilities as k → ∞.) +In addition to these inequalities we must restrict all variables to nonnegative values, and this +is achieved by adding the attribute nonnegative. The grading is set by total_degree. It +replaces the grading vector with 24 entries 1. Finally Multiplicity sets the computation +goal. +From the output file we only mention the quantity we are out for: + multiplicity = 1717/8192 + multiplicity (float) = 0.209594726562 + +Since there are 4 candidates, the probability for the existence of a Condorcet winner is 1717/2048 = +0.209595. +We can refine the information on the Condorcet paradox by computing the Hilbert series. +Either we delete Multiplicity from the input file or, better, we add --HilbertSeries (or +simply -q) on the command line. The result: + Hilbert series: + 1 5 133 363 4581 8655 69821 100915 ... 12346 890 481 15 6 + denominator with 24 factors: + 1: 1 2: 14 4: 9 + + + degree of Hilbert Series as rational function = -25 + +If your executable of Normaliz was built with CoCoALib (see Section 12), for example the +executables for Linux or Mac OS from our distribution or in the Docker image, it uses sym- + + + +metrization for the computation of the Hilbert series. If not, then simply disregard any remark +on symmetrization. Everything runs very quickly also without it. +If symmetrization has been used, you will also find a file Condorcet.symm.out in your direc- +tory. It contains the data computed for the symmetrization. You need not care at this point. +We take continue the discussion of symmetrization in Section 7.8. + + +2.10.1. Excluding ties + +Now we are more ambitious and want to compute the Hilbert series for the Condorcet para- +dox, or more precisely, the number of election outcomes having A as the Condorcet winner +depending on the number k of voters. Moreover, as it is customary in social choice theory, we +want to exclude ties. The input file changes to CondorcetSemi.in: + amb_space 24 + excluded_faces 3 + 1 1 1 1 1 1 -1 -1 -1 -1 -1 -1 1 1 -1 -1 1 -1 1 1 -1 -1 1 -1 + 1 1 1 1 1 1 1 1 -1 -1 1 -1 -1 -1 -1 -1 -1 -1 1 1 1 -1 -1 -1 + 1 1 1 1 1 1 1 1 1 -1 -1 -1 1 1 1 -1 -1 -1 -1 -1 -1 -1 -1 -1 + nonnegative + total_degree + HilbertSeries + +We could omit HilbertSeries, and the computation would include the Hilbert basis. The +type excluded_faces only affects the Hilbert series. In every other respect it is equivalent to +inequalities. +From the file CondorcetSemi.out we only display the Hilbert series: + Hilbert series: + 6 15 481 890 12346 ... 100915 69821 8655 4581 363 133 5 1 + denominator with 24 factors: + 1: 1 2: 14 4: 9 + + + shift = 1 + + + degree of Hilbert Series as rational function = -24 + +Surprisingly, this looks like the Hilbert series in the previous section read backwards, roughly +speaking. This is true, and one can explain it as we will see below. +It is justified to ask why we don’t use strict_inequalities instead of excluded_faces. +It does of course give the same Hilbert series. However, Normaliz cannot (yet) apply sym- +metrization in inhomogeneous computations. Moreover, the algorithmic approach is different, +and according to our experience excluded_faces is more efficient, independently of sym- +metrization. +See Section 7.20 for more information on excluded_faces. + + + + +2.10.2. At least one vote for every preference order + +Suppose we are only interested in elections in which every preference order is chosen by at +least one voter. This can be modeled as follows (Condorcet_one.in): + amb_space 24 + inequalities 3 + 1 1 1 1 1 1 -1 -1 -1 -1 -1 -1 1 1 -1 -1 1 -1 1 1 -1 -1 1 -1 + 1 1 1 1 1 1 1 1 -1 -1 1 -1 -1 -1 -1 -1 -1 -1 1 1 1 -1 -1 -1 + 1 1 1 1 1 1 1 1 1 -1 -1 -1 1 1 1 -1 -1 -1 -1 -1 -1 -1 -1 -1 + strict_signs + 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 + total_degree + HilbertSeries + +The entry 1 at position i of the vector strict_signs imposes the inequality xi ≥ 1. A −1 would +impose the inequality xi ≤ −1, and the entry 0 imposes no condition on the i-th coordinate. + Hilbert series: + 1 5 133 363 4581 8655 69821 100915 ... 12346 890 481 15 6 + denominator with 24 factors: + 1: 1 2: 14 4: 9 + + + shift = 24 + + + degree of Hilbert Series as rational function = -1 + + +Again we encounter (almost) the Hilbert series of the Condorcet paradox (without side con- +ditions). It is time to explain this coincidence. Let C be the Condorcet cone defined by the +nonstrict inequalities, M the monoid of lattice points in it, I1 ⊂ M the ideal of lattice points +avoiding the 3 facets defined by ties, I2 the ideal of lattice points with strictly positive coordi- +nates, and finally I3 the ideal of lattice points in the interior of C. Moreover, let 1 ∈ Z24 be the +vector with all entries 1. +Since 1 lies in the three facets defining the ties, it follows that I2 = M + 1. This explains why +we obtain the Hilbert series of I2 by multiplying the Hilbert series of M by t 24 , as just observed. +Generalized Ehrhart reciprocity (see [11, Theorem 6.70]) then explains the Hilbert series of I1 +that we observed in the previous section. Finally, the Hilbert series of I3 that we don’t have +displayed is obtained from that of M by “ordinary” Ehrhart reciprocity. But we can also obtain +I1 from I3 : I1 = I3 − 1, and generalized reciprocity follows from ordinary reciprocity in this +very special case. (Also see [16].) +The essential point in these arguments (apart from reciprocity) is that 1 lies in all support +hyperplanes of C except the coordinate hyperplanes. +You can easily compute the Hilbert series of I3 by making all inequalities strict. +As the terminal output shows, symmetrization has not been applied for the reason mentioned +above: strict_signs is an inhomogeneous input type. It would of course be possible to + + + +encode the strict signs as excluded_faces. Then the sparse format of matrices is very handy: + excluded_faces 24 + 1:1; + 1:2; + ... + 1:24; + +This is a shorthand for the unit matrix. + + +2.10.3. The f-vector with codimension bound + +Suppose we are interested in the f-vector of the cone defined by Condorcet.in. In view of the +rather high dimension the face lattice must be expected to be extremely large, but computing +the f-vector to codimension 4 should be no problem. (See [10] for the Normaliz face lattice +algorithm.) Indeed it is not. We use CondorcetFV.in: + ... + FVector + face_codim_bound 4 + +Then we find in the output file: + f-vector (possibly truncated): + 17550 2925 351 27 1 + +Note that the face numbers are listed by descending codimension or, equivalently, by increas- +ing dimension. The leftmost number is the number of faces in the highest codimension that +has been computed. So we have 17550 codimension 4 faces. + + +2.11. Testing normality +We want to test the monoid A4×4×3 defined by 4 × 4 × 3 contingency tables for normality +(see [12] for the background). The input file is A443.in: + amb_space 40 + cone_and_lattice 48 + 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 + ... + 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 1 + HilbertBasis + +Why cone_and_lattice? Well, we want to find out whether the monoid is normal, i.e., +whether M = C(M) ∩ gp(M). If M is even integrally closed in Z24 , then it is certainly inte- +grally closed in the evidently smaller lattice gp(M), but the converse does not hold in general, +and therefore we work with the lattice generated by the monoid generators. +It turns out that the monoid is indeed normal: + + + + original monoid is integrally closed in chosen lattice + +Actually the output file reveals that M is even integrally closed in Z24 : the external index is 1, +and therefore gp(M) is integrally closed in Z24 . +The output file also shows that there is a grading on Z24 under which all our generators have +degree 1. We could have seen this ourselves: Every generator has exactly one entry 1 in the +first 16 coordinates. (This is clear from the construction of M.) +A noteworthy detail from the output file: + size of partial triangulation = 48 + +It shows that Normaliz uses only a partial triangulation in Hilbert basis computations; see [12]. +It is no problem to compute the Hilbert series as well if you are interested in it. Simply add -q +to the command line or remove HilbertBasis from the input file. Then a full triangulation is +needed (size 2, 654, 272). +Similar examples are A543, A553 and A643. The latter is not normal, as we will see below. Even +on a standard PC or laptop, the Hilbert basis computation does not take very long because +Normaliz uses only a partial triangulation. The Hilbert series can still be determined, but the +computation time will grow considerably since the it requires a full triangulation. See [15] for +timings. + + +2.11.1. Computing just a witness + +If the Hilbert basis is large and there are many support hyperplanes, memory can become an +issue for Normaliz, as well as computation time. Often one is only interested in deciding +whether the given monoid is integrally closed (or normal). In the negative case it is enough +to find a single element that is not in the original monoid – a witness disproving integral +closedness. As soon as such a witness is found, Normaliz stops the Hilbert basis computation +(but will continue to compute other data if they are asked for). We look at the example A643.in +(for which the full Hilbert basis is not really a problem): + amb_space 54 + cone_and_lattice 72 + 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 ... + ... + 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 ... + WitnessNotIntegrallyClosed + + +Don’t add HilbertBasis because it will overrule IsIntegrallyClosed! +The output: + 72 extreme rays + 153858 support hyperplanes + + + + + embedding dimension = 54 + rank = 42 + external index = 1 + internal index = 1 + original monoid is not integrally closed in chosen lattice + witness for not being integrally closed: + 0 0 1 0 1 1 1 1 0 0 1 0 0 1 0 1 0 1 1 0 1 1 0 0 1 1 1 0 0 1 1 0 0 1 1 ... + + + grading: + 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 ... + + + degrees of extreme rays: + 1: 72 + + + *********************************************************************** + + 72 extreme rays: + 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 ... + ... + +If you repeat such a computation, you may very well get a different witness if several parallel +threads find witnesses. Only one of them is delivered. +If you just want to check integral closedness as quickly as possible, replace WitnessNotIntegrallyClosed +by IsIntegrallyClosed. Normaliz first checks some necessary conditions. If they are satis- +fied, the calculation of the Hilbert basis is started. If it finds a witness for not being integrally +closed, the witness is displayed in the output. + + +2.12. Convex hull computation/vertex enumeration +Normaliz computes convex hulls as should be very clear by now, and the only purpose of +this section is to emphasize that Normaliz can be restricted to this task by setting an explicit +computation goal. By convex hull computation we mean the determination of the support +hyperplanes of a polyhedron is given by generators (or vertices). The converse operation is +vertex enumeration. Both amount to the dualization of a cone, and can therefore be done by +the same algorithm. +As an example we take the input file cyclicpolytope30-15.in, the cyclic polytope of dimen- +sion 15 with 30 vertices (suggested by D. Avis and Ch. Jordan): + /* cyclic polytope of dimension 15 with 30 vertices */ + amb_space 16 + polytope 30 + 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 + 2 4 8 16 32 64 128 256 512 1024 2048 4096 8192 16384 32768 + ... + 30 900 27000 810000 ... 478296900000000000000 14348907000000000000000 + + + + + SupportHyperplanes + +Already the entries of the vertices show that the computation cannot be done in 64 bit arith- +metic. But you need not be worried. Just start Normaliz as usual. It will simply switch to +infinite precision by itself, as shown by the terminal output (use the option -c or --Verbose). + \.....| + Normaliz 3.2.0 \....| + \...| + (C) The Normaliz Team, University of Osnabrueck \..| + January 2017 \.| + \| + ************************************************************ + Compute: SupportHyperplanes + Could not convert 15181127029874798299. + Arithmetic Overflow detected, try a bigger integer type! + Restarting with a bigger type. + ************************************************************ + starting primal algorithm (only support hyperplanes) ... + Generators sorted lexicographically + Start simplex 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 + gen=17, 72 hyp + gen=18, 240 hyp + gen=19, 660 hyp + gen=20, 1584 hyp + gen=21, 3432 hyp + gen=22, 6864 hyp + gen=23, 12870 hyp + gen=24, 22880 hyp + gen=25, 38896 hyp + gen=26, 63648 hyp + gen=27, 100776 hyp + gen=28, 155040 hyp + gen=29, 232560 hyp + gen=30, 341088 hyp + Pointed since graded + Select extreme rays via comparison ... done. + ------------------------------------------------------------ + transforming data... done. + +Have a look at the output file if you are not afraid of 341088 linear forms. +If you have looked closely at the terminal output above, you should have stumbled on the lines + Could not convert 15181127029874798299. + Arithmetic Overflow detected, try a bigger integer type! + +They show that Normaliz has tried the computation in 64 bit integers, but encountered a num- + + + + +ber that is too large for this precision. It has automatically switched to infinite precision. (See +Section 5.3 for more information on integer types.) + + +2.13. Lattice points in a polytope and its Euclidean volume +The computation of lattice points in a polytope can be viewed as a truncated Hilbert basis +computation, and we have seen in preceding examples. But Normaliz can be restricted to +their computation, with homogeneous as well as with inhomogeneous input. Let us look at +ChF_8_1024.in: + + amb_space 8 + constraints 16 + 0.10976576 0.2153132834 ... 0.04282847494 >= -1/2 + ... + 0.10976576 -0.2153132834 ... -0.04282847494 >= -1/2 + 0.10976576 0.2153132834 ... 0.04282847494 <= 1/2 + 0.10976576 -0.2153132834 ...-0.04282847494 <= 1/2 + LatticePoints + ProjectionFloat + + +This example comes from numerical analysis; see Ch. Kacwin, J. Oettershagen and T. Ullrich, +On the orthogonality of the Chebyshev-Frolov lattice and applications, Monatsh. Math. 184 +(2017), 425–441). Its origin explains the decimal fractions in the input. Normaliz converts +them immediately into ordinary fractions of type numerator/denominator, and then makes the +input integral as usual. +In the output file you can see to what integer vectors Normaliz has converted the inequalities +of the input file: + 16 support hyperplanes of polyhedron (homogenized): + 5488288000 10765664170 ... 2141423747 25000000000 + ... + -5488288000 10765664170 ... 2141423747 25000000000 + +The option ProjectionFloat indicates that we want to compute the lattice points in the poly- +tope defined by the inequalities and that we want to use the floating point variant of the +project-and-lift algorithm; Projection would make Normaliz use its ordinary arithmetic in +this algorithm. For our example the difference in time is not really significant, but when you +try VdM_16_1048576.in, it becomes very noticeable. Let us have a look at the relevant part of +then terminal output: + Polyhedron is parallelotope + Computing lattice points by project-and-lift + LLL based on support hyperplanes + Projection + embdim 9 inequalities 16 + ... + + + + + embdim 6 inequalities 140 + ... + embdim 2 inequalities 2 + embdim 1 inequalities 0 + Lifting + Lifting to dimension 2 + Lifting to dimension 3 + ... + Lifting to dimension 8 + Lifting to dimension 9 + embdim 2 LatticePoints 5 + embdim 3 LatticePoints 21 + ... + embdim 8 LatticePoints 907 + embdim 9 LatticePoints 1067 + Project-and-lift complete + +We start with embedding dimension 9 since we need a homogenizing coordinate in inhomoge- +neous computations. Then the polytope is successively projected onto a coordinate hyperplane +until we reach a line segment given by 2 inequalities. In the second part Normaliz lifts the lat- +tice points back through all projections. The following figure illustrates the procedure for a +polygon that is projected to a line segment. + + + + +The green lines show the fibers over the lattice points in the (red) line segment. Note that +not every lattice point in the projection must be liftable to a lattice point in the next higher +dimension. +In ChF_8_1024.out we see + 1067 lattice points in polytope (module generators): + -4 0 0 0 0 0 0 0 1 + -3 0 0 0 -1 0 0 0 1 + -3 0 0 0 0 0 0 0 1 + ... + 3 0 0 0 0 0 0 0 1 + 3 0 0 0 1 0 0 0 1 + 4 0 0 0 0 0 0 0 1 + +Normaliz finds out that our polytope is in fact a parallelotope. This allows Normaliz to sup- +press the computation of its vertices. We are not interested in them, and they look frightening + + + +when written as ordinary fractions (computed with the additional option SupportHyperplanes). +This is only the first vertex, the denominator is the number in the last row: + 256 vertices of polyhedron: + -7831972155307708173239167258085974255845869779051329651906336771582421875 + -2560494334732147696394408175864650673712115229853232268085759500000000000 + 2411932924117448250036041241683237083742860005142447171295674845000000000 + -2170682283899852950367663781367299946065844697990214478942400250000000000 + 1846013540077621750562232333569651551559659207659438074760922800500000000 + -1450403531662801634587765586956338287943865886737024582718631750000000000 + 999055328718773316303519268629091038893656784654239444024061220000000000 + -509313990522468215816366827427428831508901797188810249435062450000000000 + 2292486335803169657316823615602461625422283571089603408672092012129842506 + ... + +Not all polytopes are parallelotopes, and in most cases Normaliz must compute the vertices or +extreme rays as an auxiliary step, even if we are not interested in them. You can always add +the option +NoExtRaysOutput +if you want to suppress their output. (The numerical information on the number of extreme +rays etc. will however be included in the output file if it is available.) Similarly one can +suppress the output of support hyperplanes by +NoSuppHypsOutput +On the other hand, the information provided by the vertices or support hyperplanes may be +important. Instead of the unreadable integer output shown above, you can ask for +VerticesFloat +Then the vertices of polyhedra are printed in floating point format: + 256 vertices of polyhedron: + -3.41637 -1.11691 1.0521 ... 0.435796 -0.222167 1 + -3.41637 -0.946868 0.435796 ... -1.0521 0.632677 1 + ... + +Note that they can only be printed if a polyhedron is defined. This is always the case in +inhomogeneous computations, but in the homogeneous case a grading is necessary. There is +also a variant ExtremeRaysFloat. +Similarly we can get the support hyperplanes in floating point format (they are only defined +up to a positive scalar multiple) by +SuppHypsFloat +resulting in + 16 support hyperplanes of polyhedron (homogenized): + -0.219532 -0.430627 -0.405641 ... -0.168022 -0.0856569 1 + -0.219532 -0.365068 -0.168022 ... 0.405641 0.24393 1 + + + + + ... + +By its construction, our polytope should have Euclidean volume 1024. We can confirm this +number by computing the volume, using the option +Volume, -V +We get + volume (normalized) = 205078125000...00/49670537275735342575...58763 + volume (normalized, float) =41287680.0308 + volume (Euclidean) = 1024.00000076 + +The result makes us happy, despite of the small inaccuracy of the floating point computation +on which the Euclidean volume is based. See Section 7.1.1 for a discussion of volumes and +multiplicities. + + +2.14. The integer hull +The integer hull of a polyhedron P is the convex hull of the set of lattice points in P (despite of +its name, it usually does not contain P). Normaliz computes by first finding the lattice points +and then computing the convex hull. The computation of the integer hull is requested by the +computation goal IntegerHull. +The computation is somewhat special since it creates a second cone (and lattice) Cint . In +homogeneous computations the degree 1 vectors generate Cint by an input matrix of type +cone_and_lattice. In inhomogeneous computations the module generators and the Hilbert +basis of the recession cone are combined and generate Cint . Therefore the recession cone is +reproduced, even if the polyhedron should not contain a lattice point. +The integer hull computation itself is always inhomogeneous. The output file for Cint is +.IntHull.out. +As a very simple example we take rationalIH.in (rational.in augmented by IntegerHull): + amb_space 3 + cone 3 + 1 1 2 + -1 -1 3 + 1 -2 4 + grading + unit_vector 3 + HilbertSeries + IntegerHull + +It is our rational polytope from Section 2.5. We know already that the origin is the only lattice +point it contains. Nevertheless let us have a look at rationalIH.IntHull.out: + 1 vertices of polyhedron + 0 extreme rays of recession cone + + + + + 1 support hyperplanes of polyhedron (homogenized) + + + embedding dimension = 3 + affine dimension of the polyhedron = 0 + rank of recession monoid = 0 (polyhedron is polytope) + internal index = 1 + + + + *********************************************************************** + + 1 vertices of polyhedron: + 0 0 1 + + + 0 extreme rays of recession cone: + + + 1 support hyperplanes of polyhedron (homogenized): + 0 0 1 + + + 2 equations: + 1 0 0 + 0 1 0 + + + 1 basis elements of generated lattice: + 0 0 1 + + +Since the lattice points in P are already known, the goal was to compute the constraints defin- +ing the integer hull. Note that all the constraints defining the integer hull can be different from +those defining P. In this case the integer hull is cit out by the 2 equations. +As a second example we take the polyhedron of Section 2.9. The integer hull is the “green” +polyhedron: + + + + +The input is InhomIneqIH.in (InhomIneq.in augmented by IntegerHull). The data of the +integer hull are found in InhomIneqIH.IntHull.out: + ... + 2 vertices of polyhedron: + -1 0 1 + 0 1 1 + + + + + 1 extreme rays of recession cone: + 1 0 0 + + + 3 support hyperplanes of polyhedron (homogenized): + 0 -1 1 + 0 1 0 + 1 -1 1 + + + + +2.15. Inhomogeneous congruences +We want to compute the nonnegative solutions of the simultaneous inhomogeneous congru- +ences + + x1 + 2x2 ≡ 3 (7), + 2x1 + 2x2 ≡ 4 (13) + +in two variables. The input file InhomCong.in is + amb_space 2 + constraints 2 symbolic + x[1] + 2x[2] ~ 3 (7); + 2x[1] + 2x[2] ~ 4 (13); + +This is an example of input of symbolic constraints. We use ~ as the best ASCII character for +representing the congruence sign ≡. +Alternatively one can use a matrix in the input As for which we must move the right hand side +over to the left. + amb_space 2 + inhom_congruences 2 + 1 2 -3 7 + 2 2 -4 13 + +It is certainly harder to read. +The first vector list in the output: + 3 module generators: + 0 54 1 + 1 1 1 + 80 0 1 + + +Easy to check: if (1, 1) is a solution, then it must generate the module of solutions together +with the generators of the intersections with the coordinate axes. Perhaps more difficult to +find: + 6 Hilbert basis elements of recession monoid: + 0 91 0 + + + + + 1 38 0 + 3 23 0 1 vertices of polyhedron: + 5 8 0 0 0 91 + 12 1 0 + 91 0 0 + +Strange, why is (0, 0, 1), representing the origin in R2 , not listed as a vertex as well? Well the +vertex shown represents an extreme ray in the lattice E, and (0, 0, 1) does not belong to E. + 2 extreme rays of recession cone: + 0 91 0 + 91 0 0 + + + 3 support hyperplanes of polyhedron (homogenized) + 0 0 1 + 0 1 0 + 1 0 0 + + + 1 congruences: + 58 32 1 91 + + +Normaliz has simplified the system of congruences to a single one. + 3 basis elements of generated lattice: + 1 0 33 + 0 1 -32 + 0 0 91 + +Again, don’t forget that Normaliz prints a basis of the efficient lattice E. + + +2.15.1. Lattice and offset + +The set of solutions to the inhomogeneous system is an affine lattice in R2 . The lattice basis +of E above does not immediately let us write down the set of solutions in the form w + L0 with +a subgroup L0 , but we can easily transform the basis of E: (1, 1, 1) is in E and we use it to +reduce the third column of the other two basis elements to 0. Try the file InhomCongLat.in: + amb_space 2 + offset + 1 1 + lattice 2 + 5 8 + -12 -1 + + + + +2.15.2. Variation of the signs + +Suppose we want to solve the system of congruences under the condition that both variables +are negative (InhomCongSigns.in): + amb_space 2 + inhom_congruences 2 + 1 2 -3 7 + 2 2 -4 13 + signs + -1 -1 + + +The two entries of the sign vector impose the sign conditions x1 ≤ 0 and x2 ≤ 0. +From the output we see that the module generators are more complicated now: + 4 module generators: + -11 0 1 + -4 -7 1 + -2 -22 1 + 0 -37 1 + +The Hilbert basis of the recession monoid is simply that of the nonnegative case multiplied by +−1. + + +2.16. Integral closure and Rees algebra of a monomial ideal +Next, let us discuss the example MonIdeal.in (typeset in two columns): + amb_space 5 + rees_algebra 9 + 1 2 1 2 1 0 3 4 + 3 1 1 3 5 1 0 1 + 2 5 1 0 2 4 1 5 + 0 2 4 3 2 2 2 4 + 0 2 3 4 + + +The input vectors are the exponent vectors of a monomial ideal I in the ring K[X1 , X2 , X3 , X4 ]. +We want to compute the normalization of the Rees algebra of the ideal. In particular we can +extract from it the integral closure of the ideal. Since we must introduce an extra variable T , +we have amb_space 5. +In the Hilbert basis we see the exponent vectors of the Xi , namely the unit vectors with last +component 0. The vectors with last component 1 represent the integral closure I of the ideal. +There is a vector with last component 2, showing that the integral closure of I 2 is larger than I . + 16 Hilbert basis elements: + 0 0 0 1 0 + + + + + ... + 5 1 0 1 1 + 6 5 2 2 2 + + + 11 generators of integral closure of the ideal: + 0 2 3 4 + ... + 5 1 0 1 + +The output of the generators of I is the only place where we suppress the homogenizing vari- +able for “historic” reasons. If we extract the vectors with last component 1 from the extreme +rays, then we obtain the smallest monomial ideal that has the same integral closure as I. + 10 extreme rays: + 0 0 0 1 0 + ... + 5 1 0 1 1 + +The support hyperplanes which are not just sign conditions describe primary decompositions +of all the ideals I k by valuation ideals. It is not hard to see that none of them can be omitted for +large k (for example, see: W. Bruns and G. Restuccia, Canonical modules of Rees algebras. J. +Pure Appl. Algebra 201, 189–203 (2005)). + 23 support hyperplanes: + 0 0 0 0 1 + 0 ... + 6 0 1 3 -13 + + + +2.16.1. Only the integral closure of the ideal + +If only the integral closure of the ideal is to be computed, one can choose the input as follows +(IntClMonId.in): + amb_space 4 + vertices 9 + 1 2 1 2 1 + ... + 2 2 2 4 1 + cone 4 + 1 0 0 0 + 0 1 0 0 + 0 0 1 0 + 0 0 0 1 + +The generators of the integral closure appear as module generators in the output and the gen- +erators of the smallest monomial ideal with this integral closure are the vertices of the polyhe- +dron. + + + +4. The input file +The input file .in consists of items. There are several types of them: + (1) definition of the ambient space, + (2) matrices with integer or rational entries (depending on the type), + (3) vectors with integer entries, + (4) constraints in tabular or symbolic format, + (5) a polynomial, + (6) computation goals and algorithmic variants, + (7) numerical parameters, + (8) number field definition, + (9) input types for fusion rings, +(10) comments. +An item cannot include another item. In particular, comments can only be inserted between +other items, but not within another item. Matrices and vectors can have two different formats, +plain and formatted. +Matrices and vectors are classified by the following attributes: + (1) generators, constraints, accessory, + (2) cone/polyhedron, (affine) lattice, + (3) homogeneous, inhomogeneous. +The line structure is irrelevant for the interpretation of the input, but it is advisable to use it for +the readability of the input file. +The input syntax of Normaliz 2 can still be used. It is explained in Appendix C. + + +4.1. Input items +4.1.1. The ambient space and lattice + +The ambient space is specified as follows: + amb_space + +where stands for the dimension d of the ambient vector space Rd in which the geometric +objects live. The ambient lattice A is set to Zd . +Alternatively one can define the ambient space implicitly by + amb_space auto + +In this case the dimension of the ambient space is determined by Normaliz from the first +formatted vector or matrix in the input file. It is clear that any input item that requires the +knowledge of the dimension can only follow the first formatted vector or matrix. +In the following the letter d will always denote the dimension set with amb_space. + + + +An example: + amb_space 5 + +indicates that polyhedra and lattices are subobjects of R5 . The ambient lattice is Z5 . +The first non-comment input item must specify the ambient space. + + +4.1.2. Plain vectors + +A plain vector is built as follows: + + + + denotes the type and is the vector itself. The number of components is determined +by the type of the vector and the dimension of the ambient space. At present, all vectors have +length d. +Example: + grading + 1 0 0 + +Normaliz allows also the input of sparse vectors. Sparse input is signalized by the key word +sparse as the first entry. It is followed by entries of type : where denotes +the column and the value in that column. (The unspecified columns have entry 0.) A +sparse vector is terminated by the character ; . Example: + grading + sparse 1:1; + +One can also set a range of entries in sparse vectors like in + grading + sparse 1:1 3..5:-1 7:1; + +which produces the vector (1, 0, −1, −1, −1, 0, 1, 0 . . . , 0). +For unit vectors vectors there exists a shortcuts. Example: + total_degree + unit_vector 25 + + + +4.1.3. Formatted vectors + +A formatted vector is built as follows: + + [ ] + + + + +where denotes the type and is the vector itself. The components can be separated +by white space, commas or semicolons. An example showing all possibilities (not recom- +mended): + grading + [1,0; 0 5] + + + +4.1.4. Plain matrices + +A plain matrix is built as follows: + + + ... + + +Here denotes the type of the matrix, the number of rows, and ,. . . , are +the rows. Some types allow rational and floating point matrix entries, others are restricted to +integers; see Sections 4.1.9 and 4.1.10. +The number of columns is implicitly defined by the dimension of the ambient space and the +type of the matrix. Example (with amb_space 3): + cone 3 + 1/3 2 3 + 4 5 6 + 11 12/7 13/21 + +Normaliz allows the input of matrices in transposed form: + transpose + + ... + + +Note that is now the number of columns of the matrix that follows it (assumed to be the +number of input vectors). The number of rows is determined by the dimension of the ambient +space and the type of the matrix. Example: + cone transpose 3 + 1 0 3/2 + 0 1/9 4 + +is equivalent to + cone 3 + 1 0 + 0 1/9 + 3/2 4 + + + + +Like vectors, matrices have a sparse input variant, again signalized by the key word sparse. +The rows are sparse vectors with entries :, and each row is concluded by the +character ;. Also here one can set a range of coordinates to the same value: +Example: + inequalities 2 sparse + 1:1 2:-1; + 3-5:-1; + +chooses the 3 × 3 unit matrix as a matrix of type inequalities. Note that also in case of +transposed matrices, sparse entry is row by row. +Matrices may have zero rows. Such empty matrices like + inhom_inequalities 0 + +can be used to make the input inhomogeneous (Section 4.1.17) or to avoid the automatic choice +of the positive orthant in certain cases (Section 4.1.18). (The empty inhom_inequalities have +both effects simultaneously.) Apart from these effects, empty matrices have no influence on +the computation. + + +4.1.5. Formatted matrices + +A formatted matrix is built as follows: + + [ [] + ... + [] ] + +Here denotes the type of the matrix and ,. . . , are vectors. Legal separators +are white space, commas and semicolons. An example showing all possibilities (not really +recommended): + cone [ + [ 2 1][3/7 4]; + [0 1], + [9 10] [11 12/13] + ] + +Similarly as plain matrices, formatted matrices can be given in transposed form, and they can +be empty. + + +4.1.6. Constraints in tabular format + +This input type is somewhat closer to standard notation than the encoding of constraints in +matrices. The general type of equations and inequalities is + + + + + ; + +where denotes a vector of length d, is one of the relations =, <=, >=, <, > and +is a number. +Congruences have the form + ~ (); + +where is a nonzero integer. +Examples: + 1/2 -2 >= 0.5 + 1 -1/7 = 0 + -1 1 ~ 7 (9) + +Note: all numbers and relation signs must be separated by white space. + + +4.1.7. Constraints in symbolic format + +This input type is even closer to standard notation than the encoding of constraints in matrices +or in tabular format. It is especially useful if the constraints are sparse. Instead of assigning a +value to a coordinate via its position in a vector, it uses coordinates named x[] where +is the index of the coordinate. The index is counted from 1. +The general type of equations and inequalities is + ; + +where and denote affine linear function of the x with rational coefficients. As +above, is one of the relations =, <=, >=, <, >. (Both and must be nonempty.) +Note the terminating semicolon. +Congruences have the form + ~ (); + +where is a nonzero integer and and are affine linear functions with integer +coefficients. +Examples: + 1/3x[1] >= 2x[2] + 5; + x[1]+1=1/4x[2] ; + -x[1] + x[2] ~ 7 (9); + +There is no need to insert white space for separation, but it may be inserted anywhere where +it does not disrupt numbers or relation signs. + + + + +4.1.8. Polynomials + +For the computation of weighted Ehrhart series and integrals Normaliz needs the input of +a polynomial with rational coefficients. Moreover, one can apply polynomial constraints to +lattice points in polytopes. A polynomial is first read as a string. For the computation the +string is converted by the input function of CoCoALib [2]. Therefore any string representing +a valid CoCoA expression is allowed. However, the names of the indeterminates are fixed: +x[1],. . . ,x[ where ] is the value of amb_space. The polynomial must be concluded by +a semicolon. +Example: + (x[1]+1)*(x[1]+2)*(x[1]+3)*(x[1]+4)*(x[1]+5)* + (x[2]+1)*(x[3]+1)*(x[4]+1)*(x[5]+1)*(x[6]+1)*(x[7]+1)* + (x[8]+1)*(x[8]+2)*(x[8]+3)*(x[8]+4)*(x[8]+5)*1/14400; + + + (x[1]*x[2]*x[3]*x[4])^2*(x[1]-x[2])^2*(x[1]-x[3])^2* + (x[1]-x[4])^2*(x[2]-x[3])^2*(x[2]-x[4])^2*(x[3]-x[4])^2; + + + +4.1.9. Rational numbers + +Rational numbers are allowed in input matrices, but not in all. They are not allowed in vectors +and in matrices containing lattice generators and in congruences, namely in + lattice cone_and_lattice offset open_facets + congruences inhom_congruences rees_algebra lattice_ideal + grading dehomogenization signs strict_signs + +They are allowed in saturation since it defines the intersection of the vector space generated +by the rows of the matrix with the integral lattice. +Avoid negative numbers as denominators. +Normaliz first reduces the input numbers to lowest terms. Then each row of a matrix is mul- +tiplied by the least common multiple of the denominators of its entries. In all applications +in which the original monoid generators play a role, one should use only integers in input +matrices to avoid any ambiguity. + + +4.1.10. Decimal fractions and floating point numbers + +Normaliz accepts decimal fractions and floating point numbers in its input files. These are +precisely converted to ordinary fractions (or integers). Examples: + 1.1 --> 11/10 0.5 --> 1/2 -.1e1 --> -1 + +It is not allowed to combine an ordinary fraction and a decimal fraction in the same number. +In other words, expressions like 1.0/2 are not allowed. + + + + +4.1.11. Numbers in algebraic extensions of Q + +Their format is explained in Section 8.1 together with the definition of number fields. + +4.1.12. Numerical parameters + +Their input has the form + + +where is the value assigned to . + +4.1.13. Computation goals and algorithmic variants + +These are single or compound words, such as + HilbertBasis + Multiplicity + +The file can contain several computation goals, as in this example. + +4.1.14. Input types for fusion rings + +See Appendix H. + +4.1.15. Comments + +A comment has the form + /* */ + +where stands for the text of the comment. It can have arbitrary length and stretch over +several lines. Example: + /* This is a comment + */ + +Comments are only allowed at places where also a new keyword would be allowed, especially +not between the entries of a matrix or a vector. Comments can not be nested. + +4.1.16. Restrictions + +Input items can be combined quite freely, but there are some restrictions: + (1) The types + cone, cone_and_lattice, polytope, rees_algebra + exclude each other mutually. + + + + (2) The input type subspace excludes polytope and rees_algebra. + (3) The types + lattice, saturation, cone_and_lattice + exclude each other mutually. + (4) polytope can not be combined with grading. + (5) The only type that can be combined with lattice_ideal is grading. + (6) The following types cannot be combined with inhomogeneous types or dehomogenization: + polytope, rees_algebra, excluded_faces + (7) The following types cannot be combined with inhomogeneous types: + dehomogenization + (8) Special restrictions apply for the input type open_facets; see Section 4.15. + (9) Special rules apply if precomputed data are used. See Section 7.23. +(10) For restrictions that apply to algebraic polyhedra see Section 8. Similar restrictions + apply if the input types rational_lattice and rational_offset are used (see Sec- + tion 7.21). +(11) The input types monoid, toric_ideal, normal_toric_ideal and lattice_ideal al- + loow only grading as a further input type. +A non-restriction: the same type can appear several times. This is useful if one wants to +combine different formats, for example + inequalities 2 sparse + 1:1; + 1:1 3:-1; + inequalities 2 + 1 1 0 1 + 1 -1 -1 0 + + + +4.1.17. Homogeneous and inhomogeneous input + +Apart from the restrictions listed in the previous section, homogeneous and inhomogeneous +types can be combined as well as generators and constraints. A single inhomogeneous type +or dehomogenization in the input triggers an inhomogeneous computation. The input item of +inhomogeneous type may be an empty matrix. + + +4.1.18. Default values + +If there is no lattice defining item, Normaliz (virtually) inserts the the unit matrix as an input +item of type lattice. If there is no cone defining item, the unit matrix is (additionally) inserted +as an input item of type cone. +If the input is inhomogeneous, then Normaliz provides default values for vertices and the +offset as follows: + (1) If there is an input matrix type lattice, but no offset, then the offset 0 is inserted. + + + + (2) If there is an input matrix of type cone, but no vertices, then the vertex 0 is inserted. +An important point. If the input does not contain any cone generators or inequalities, Nor- +maliz automatically assumes that you want to compute in the positive orthant. In order to +avoid this you can use the directive +no_pos_orth_def +Equivalently you can add an empty matrix of inequalities, inhom_inequalities or strict_inequalities. +This will not affect the results. + + +4.1.19. Normaliz takes intersections + +The input may contain several cone defining items and several lattice defining items. We con- +sider homogeneous input for simplicity. Inhomogeneous input is made homogeneous anyway. +One can subdivide the input items defining cones and lattices as follows: + 1. cone generators: together they generate a cone C1 ; + 2. cone constraints, namely inequalities and equations: they define the cone C2 ; + 3. lattice generators: they generate the sublattice L1 and the vector subspace U1 = RL1; + 4. lattice constraints, namely equations and congruences: they define the sublattice L2 and + the vector subspace U2 = RL2 . +The cone defined by all these data is C=C1 ∩ C2 ∩ U1 ∩ U2 . The lattice defined by them is +RC ∩ L1 ∩ L2 . + + +4.2. Homogeneous generators +4.2.1. Cones + +The main type is cone. The other two types are added for special computations. +cone is a matrix with d columns. Every row represents a vector, and they define the cone + generated by them. Section 2.3, 2cone.in +subspace is a matrix with d columns. The linear subspace generated by the rows is added to + the cone. Section 7.13.4. +polytope is a matrix with d − 1 columns. It is internally converted to cone extending each + row by an entry 1. Section 2.4, polytope.in. This input type automatically sets + NoGradingDenom and defines the grading (0, . . . , 0, 1). Not allowed in combination with + inhomogeneous types. +rees_algebra is a matrix with d − 1 columns. It is internally converted to type cone in two + steps: (i) each row is extended by an entry 1 to length d. (ii) The first d − 1 unit vectors + of length d are appended. Section 2.16, MonIdeal.in. Not allowed in combination with + inhomogeneous types. +extreme_rays is a matrix with d columns. See Section 7.23 for its use. +maximal_subspace is a matrix with d columns. See Section 7.23 for its use. + + + + +Moreover, it is possible to define a cone and a lattice by the same matrix: +cone_and_lattice The vectors of the matrix with d columns define both a cone and a lattice. + Section 2.11, A443.in. + If subspace is used in combination with cone_and_lattice, then the sublattice gener- + ated by its rows is added to the lattice generated by cone_and_lattice. +The Normaliz 2 types integral_closure and normalization can still be used. They are +synonyms for cone and cone_and_lattice, respectively. + + +4.2.2. Lattices + +There are 5 types. With the exception of rational_lattice and saturation their entries are +integers. +lattice is a matrix with d columns. Every row represents a vector, and they define the lattice + generated by them. Section 2.6.3, 3x3magiceven_lat.in. +rational_lattice is a matrix with d columns. Its entries can be fractions. Every row repre- + sents a vector, and they define the sublattice of Qd generated by them. See Section 7.21, + ratlat_2.in. +saturation is a matrix with d columns. Every row represents a vector, and they define the lat- + tice U ∩Zd where U is the subspace generated by them. Section 2.6.3, 3x3magic_sat.in. + (If the vectors are integral, then U ∩Zd is the saturation of the lattice generated by them.) +cone_and_lattice See Section 4.2.1. +generated_lattice is a matrix with d columns. See Section 7.23 for its use. +hilbert_basis_rec_cone is a matrix with d columns. It contains the precomputed Hilbert + basis of the recession cone. See Section 7.23.3. + + +4.2.3. Affine monoids + +monoid is a matrix with d columns. Every row represents a vector, and they generate a sub- + monoid of Z. See Section 3, monoid.in, A443monoid.in. + + +4.3. Homogeneous Constraints +The coefficients ξi of the constraints are rational numbers unless indicated otherwise. + + +4.3.1. Cones + +inequalities is a matrix with d columns. Every row (ξ1 , . . . , ξd ) represents a homogeneous + inequality + ξ1 x1 + · · · + ξd xd ≥ 0 + for the vectors (x1 , . . . , xd ) ∈ Rd . Sections 2.3.2, 2.5.2, 2cone_ineq.in, poly_ineq.in + + + + +equations is a matrix with d columns. Every row (ξ1 , . . . , ξd ) represents an equation + + ξ1 x1 + · · · + ξd xd = 0 + for the vectors (x1 , . . . , xd ) ∈ Rd . Section 2.6, 3x3magic.in +signs is a vector with d entries in {−1, 0, 1}. It stands for a matrix of type inequalities + composed of the sign inequalities xi ≥ 0 for the entry 1 at the i-th component and the + inequality xi ≤ 0 for the entry −1. The entry 0 does not impose an inequality. See + Section 2.15.2, InhomCongSigns.in. +excluded_faces is a matrix with d columns. Every row (ξ1 , . . . , ξd ) represents an inequality + + ξ1 x1 + · · · + ξd xd > 0 + for the vectors (x1 , . . . , xd ) ∈ Rd . It is considered as a homogeneous input type though + it defines inhomogeneous inequalities. The faces of the cone excluded by the inequali- + ties are excluded from the Hilbert series computation, but excluded_faces behave like + inequalities in almost every other respect. Section 2.10.1, CondorcetSemi.in. Also + see Section 7.20. +support_hyperplanes is a matrix with d columns. See Section 7.23. +A useful shortcut: +nonnegative inserts the sign inequalities xi ≥ 0 for all coordinates. See Condorcet.in. + + +4.3.2. Lattices + +congruences is a matrix with d +1 columns. Each row (ξ1 , . . . , ξd , c) represents a congruence + + ξ1 z1 + · · · + ξd zd ≡ 0 mod c, ξi , c ∈ Z, + for the elements (z1 , . . . , zd ) ∈ Zd . Section 2.6.2, 3x3magiceven.in. + + +4.4. Inhomogeneous generators +4.4.1. Polyhedra + +vertices is a matrix with d +1 columns. Each row (p1 , . . . , pd , q), q > 0, specifies a generator + of a polyhedron (not necessarily a vertex), namely +   + p1 pn + vi = ,..., , pi ∈ Q, q ∈ Q>0 , + q q + Section 2.9.1, InhomIneq_gen.in + Note: vertices and cone together define a polyhedron. If vertices is present in the + input, then the default choice for cone is the empty matrix. +The format of vertices was introduced when Normaliz only accepted integer numbers in its +input. There is no need for an extra denominator anymore, but for backward compatibility the +format has not been changed. +The Normaliz 2 input type polyhedron can still be used. + + + +4.4.2. Affine lattices + +offset is a vector with d integer entries. It defines the origin of the affine lattice. Sec- + tion 2.15.1, InhomCongLat.in. +rational_offset is a vector with d rational entries. It defines the origin of the rational affine + lattice. Section 7.21, ratlat_2.in. +Note: offset and lattice (or saturation) together define an affine lattice. If offset is +present in the input, then the default choice for lattice is the empty matrix. + + +4.5. Inhomogeneous constraints +4.5.1. Polyhedra + +inhom_inequalities is a matrix with d + 1 columns. We consider inequalities + + ξ1 x1 + · · · + ξd xd ≥ η, + + rewritten as + ξ1 x1 + · · · + ξd xd + (−η) ≥ 0 + and then represented by the input vectors + + (ξ1 , . . . , ξd , −η). + + Section 2.9, InhomIneq.in. +inhom_equations is a matrix with d + 1 columns. We consider equations + + ξ1 x1 + · · · + ξd xd = η, + + rewritten as + ξ1 x1 + · · · + ξd xd + (−η) = 0 + and then represented by the input vectors + + (ξ1 , . . . , ξd , −η). + + See Section 2.7NumSemi.in. +strict_inequalities is a matrix with d columns. We consider inequalities + + ξ1 x1 + · · · + ξd xd ≥ 1, + + represented by the input vectors + (ξ1 , . . . , ξd ). + Section 2.3.3, 2cone_int.in. +strict_signs is a vector with d components in {−1, 0, 1}. It is the “strict” counterpart to + signs. An entry 1 in component i represents the inequality xi > 0, an entry −1 the oppo- + site inequality, whereas 0 imposes no condition on xi . Section 2.10.2, Condorcet_one.in + + + +inhom_excluded_faces is a matrix with d + 1 columns. Every row (ξ1 , . . . , ξd , −η) repre- + sents an inequality + ξ1 x1 + · · · + ξd xd > η + for the vectors (x1 , . . . , xd ) ∈ Rd . The faces of the polyhedron excluded by the in- + equalities are excluded from the Hilbert and Ehrhart series series computation, but + inhom_excluded_faces behave like inhom_inequalities in almost every other re- + spect. See Section 7.20. + + +4.5.2. Affine lattices + +inhom_congruences We consider a matrix with d + 2 columns. Each row (ξ1 , . . . , ξd , −η, c) + represents a congruence + + ξ1 z1 + · · · + ξd zd ≡ η mod c, ξi , η, c ∈ Z, + + for the elements (z1 , . . . , zd ) ∈ Zd . Section 2.15, InhomCongSigns.in. + + +4.6. Tabular constraints +constraints allows the input of equations, inequalities and congruences in a for- + mat that is close to standard notation. As for matrix types the keyword constraints + is followed by the number of constraints. The syntax of tabular constraints has been + described in Section 4.2.1. If (ξ1 , . . . , ξd ) is the vector on the left hand side and η the + number on the right hand side, then the constraint defines the set of vectors (x1 , . . . , xd ) + such that the relation + ξ1 x1 + · · · + ξd xd rel η + is satisfied, where rel can take the values =, ≤, ≥, <, > with the represented by input + strings =,<=,>=,<,>, respectively. + Tabular constraints cannot be used for excluded_faces or inhom_excluded_faces. + A further choice for rel is ~. It represents a congruence ≡ and requires the additional + input of a modulus: the right hand side becomes η(c). It represents the congruence + + ξ1 x1 + . . . ξd xd ≡ η (mod c). + + Sections 2.3.3, 2cone_int.in, 2.6.2, 3x3magiceven.in, 2.9, InhomIneq.in. +A right hand side ̸= 0 makes the input inhomogeneous, as well as the relations < and >. Strict +inequalities are always understood as conditions for integers. So + + ξ1 x1 + · · · + ξd xd < η + +is interpreted as + ξ1 x1 + . . . ξd xd ≤ η − 1, + + + + +4.6.1. Forced homogeneity + +It is often more natural to write constraints in inhomogeneous form, even when one wants the +computation to be homogeneous. The type constraints does not allow this. Therefore we +have introduced +hom_constraints for the input of equations, non-strict inequalities and congruences in the + same format as constraints, except that these constraints are meant to be for a homo- + geneous computation. It is clear that the left hand side has only d − 1 entries now. See + Section 2.5.2, poly_hom_const.in. + + +4.7. Symbolic constraints +The input syntax is +constraints symbolic where is the number of constraints in symbolic form that + follow. +The constraints have the form described in Section 4.1.7. Note that every symbolic constraint +(including the last) must be terminated by a semicolon. +See Sections 2.7, NumSemi.in, 2.15, InhomCong.in. +The interpretation of homogeneity follows the same rules as for tabular constraints. The vari- +ant hom_constraints is allowed and works as for tabular constraints. + + +4.8. Blocking the coordinate transformation +For certain tasks Normaliz must perform a coordinate transformation. Without an option +blocking it, it is performed if at least one of the following is contained in the input: + (1) generators, + (3) equations, + (2) congruemces. +It is difficult for Normaliz to predict whether the coordinate transformation is really necessary. +The main task for which it is superfluous is the computation of lattice points by project-and- +lift, provided there are only equations, inequalities and congruences in the input. In case (1) +the coordinate transformation cannot be blocked, and an attempt to do it will result in an +BadInputException. +You can always ask for +convert_equations +namely into inequalities. This is a harmless step, and it will often block the coordinate trans- +formation in the input phase. This does not completely avoid the coordinate transformation in +case (3). Then the directive +no_coord_transf + + + + +can be used. It implies convert_equations. +The coordinate transformation tries to simplify the coordinate system by LLL reduction, at +least in low dimensions. This can be an arithmetically dangerous step. Adding NoLLL to your +cone properties may be useful then. + + +4.9. Polynomial constraints +Normaliz can apply polynomial constraints to lattice points in polytopes. The input syntax is +polynomial_equations +polynomial_inequalities +where is the number of polynomials that follow. The equations defined by a polynomial +f is always given by f (x) = 0, and the inequality is f (x) ≥ 0. Therefore no relation signs or +“right hand sides” are allowed.Don’t forget to conclude every polynomial by a semicolon. +See pet.in, baby.in and Section 7.2.5. + + +4.10. Binomial ideals +There are three types of input for binomial ideals. The rows of the matrices coming with these +input types represent binomials. The representation of binomials by vectors is discussed in +Section 3.1.2. +The input types differ in the object computed from them. +lattice_ideal is an integer matrix with d columns. The object computed from the binomials + in it is the smallest lattice ideal containing them. Section 3.3, non_toric.in. +toric_ideal is an integer matrix with d columns. The object computed from the binomials + in it is the smallest toric ideal containing them and the toric ring whose defining ideal + the latter is. Section 3.2.1, toric_ideal.in. +normal_toric_ideal is an integer matrix with d columns. The object computed from the + binomials in it is the the normalization of the toric ring it defines. Section 3.2.2, + normal_toric_ideal.in. + + + +4.11. Unit vectors and unit matrix +A grading or a dehomogenization is often given by a unit vector: +unit_vector represents the n-th unit vector in Rd where n is the number given by . +This shortcut cannot be used as a row of a matrix. It can be used whenever a single vec- +tor is asked for, namely after grading, dehomogenization, signs and strict_signs. See +Section 2.5, rational.in. +The unit matrix can be given to every input type that expects a matrix: +unit_matrix + + + + +Example: + cone unit_matrix + +The number of rows is defined by amb_space and the type of the matrix, as usual. + + +4.12. Grading +This type is accessory. A Z-valued grading can be specified in two ways: + (1) explicitly by including a grading in the input, or + (2) implicitly. In this case Normaliz checks whether the extreme integral generators of the + monoid lie in an (affine) hyperplane A given by an equation λ (x) = 1 with a Z-linear + form λ . If so, then λ is used as the grading. + Implicit gradings are only possible for homogeneous computations. + If the attempt to find an implicit grading causes an arithmetic overflow and verbose has + been set (say, by the option-c), then Normaliz issues the warning + Giving up the check for a grading + + If you really need this check, rerun Normaliz with a bigger integer type. +Explicit definition of a grading: +grading is a vector of length d representing the linear form that gives the grading. Section 2.5, + rational.in. + _ +total degree represents a vector of length d with all entries equal to 1. Section 2.10, + Condorcet.in. +Before Normaliz can apply the degree, it must be restricted to the effective lattice E. Even if +the entries of the grading vector are coprime, it often happens that all degrees of vectors in E +are divisible by a greatest common divisor g > 1. Then g is extracted from the degrees, and it +will appear as denominator in the output file. +Normaliz checks whether all generators of the (recession) monoid have positive degree (after +passage to the quotient modulo the unit group in the nonpointed case). Vertices of polyhedra +may have degrees ≤ 0. + + +4.12.1. With binomial ideal input + +In this case the unit vectors correspond to generators of the monoid. Therefore the degrees +assigned to them must be positive. Moreover, the vectors in the input represent binomial +relations, and these must be homogeneous. In other words, both monomials in a binomial +must have the same degree. This amounts to the condition that the input vectors have degree +0. Normaliz checks this condition. + + + + +4.13. Dehomogenization +Like grading this is an accessory type. +Inhomogeneous input for objects in Rd is homogenized by an additional coordinate and then +computed in Rd+1 , but with the additional condition xd+1 ≥ 0, and then dehomogenizing all +results: the substitution xd+1 = 1 acts as the dehomogenization, and the inhomogeneous input +types implicitly choose this dehomogenization. +Like the grading, one can define the dehomogenization explicitly: +dehomogenization is a vector of length d representing the linear form δ . +The dehomogenization can be any linear form δ satisfying the condition δ (x) ≥ 0 on the cone +that is truncated. (In combination with constraints, the condition δ (x) ≥ 0 is automatically +satisfied since δ is added to the constraints.) +The input type dehomogenization can only be combined with homogeneous input types, but +makes the computation inhomogeneous, resulting in inhomogeneous output. The polyhedron +computed is the intersection of the cone C (and the lattice E) with the hyperplane given by +δ (x) = 1, and the recession cone is C ∩ {x : δ (x) = 0}. +A potential application is the adaptation of other input formats to Normaliz. The output must +then be interpreted accordingly. +Section 7.11, dehomogenization.in. + + +4.14. Weight vector for Gröbner bases +For the computation of Gröbner bases one can specify a weight vector by +gb_weight +It is a vecor with nonnegative entries for Lex as a tiebreaker and positive entries for RevLeX +(default choice). The length depends on the type of input. See Section 3.1.2 for a discussion +and examples. + + +4.15. Open facets +The input type open_facets is similar to strict_inequalities. However, it allows to apply +strict inequalities that are not yet known. This makes only sense for simplicial polyhedra +where a facet can be identified by the generator that does not lie in it. +open_facets is a vector with entries ∈ {0, 1}. +The restrictions for the use of open facets are the following: + (1) Only the input types cone, vertices and grading can appear together with open_facets. + (2) The vectors in cone are linearly independent. + (3) There is at most one vertex. +The number of vectors in cone may be smaller than d, but open_facets must have d entries. + + + +open_facets make the computation inhomogeneous. They are interpreted as follows. Let v +be the vertex—if there are no vertices, then v is the origin. The shifted C′ = v + C is cut +out by affine-linear inequalities λi (x) ≥ 0 with coprime integer coefficients. We number these +in such a way that λi (v + ci ) ̸= 0 for the generators ci of C (in the input order), i = 1, . . . , n. +Then all subsequent computations are applied to the shifted cone C′′ = v′ + C defined by the +inequalities + λi (x) ≥ ui +where the vector (u1 , . . . , ud ) is given by open_facets. (If dimC < d, then the entries u j with +j > dimC are ignored.) +That 1 indicates “open” is in accordance with its use for the disjoint decomposition; see Sec- +tion 7.14.2. Section 7.19 discusses an example. + + +4.16. Coordinates for projection +The coordinates of a projection of the cone can be chosen by +projection_coordinates It is a 0-1 vector of length d. +The entries 1 mark the coordinates of the image of the projection. The other coordinates give +the kernel of the projection. See Section 7.12 for an example. + + +4.17. Numerical parameters +Certain numerical parameters used by Normaliz can (only) be set in the input file. + + +4.17.1. Degree bound for series expansion + +It can be set by +expansion_degree +where is the number of coefficients to be computed and printed. See Section 7.10. + + +4.17.2. Number of significant coefficients of the quasipolynomial + +It can be set by +nr_coeff_quasipol +where is the number of highest coefficients to be printed. See Section 7.10.3. + + +4.17.3. Codimension bound for the face lattice + +It can be set by +face_codim_bound + + + + +where is the bound for the codimension of the faces to be computed. + + +4.17.4. Degree bounds for Markov and Gröbbner bases + +gb_degree_bound sets the upper bound for Markov and Gröbner bases, +gb_min_degree sets the lower bound for Markov and Gröbner bases. + + +4.17.5. Number of digits for fixed precision + +The computation of vilumes by signed decomposition can be done with a fixed precision. It is +et by +decimal_digits +where sets the precision to 10−n . + + +4.17.6. Block size for distributed computation + +See Appendix F.1 for an explanation. It is set by +block_size_hollow_tri + + + +4.18. Pointedness +Since version 3.1 Normaliz can also compute nonpointed cones and polyhedra without ver- +tices. + + +4.19. The zero cone +The zero cone with an empty Hilbert basis is a legitimate object for Normaliz. Nevertheless a +warning message is issued if the zero cone is encountered. + + + + +5. Computation goals and algorithmic variants +The library libnormaliz contains a class ConeProperties that collects computation goals, +algorithmic variants and additional data that are used to control the work flow in libnormaliz +as well as the communication with other programs. The latter are not important for the Nor- +maliz user, but are listed as a reference for libnormaliz. See Appendix D for a description of +libnormaliz. +All computation goals and algorithmic variants can be communicated to Normaliz in two +ways: + (1) in the input file, for example HilbertBasis, + (2) via a verbatim command line option, for example --HilbertBasis. +For the most important choices there are single letter command line options, for example -N +for HilbertBasis. The single letter options ensure backward compatibility to Normaliz 2. In +jNormaliz they are also accessible via their full names. +Some computation goals apply only to homogeneous computations, and some others make +sense only for inhomogeneous computations. +Some single letter command line options combine two or more computation goals, and some +algorithmic variants imply computation goals. +There are restrictions for algebraic polyhedra. See Section 8.3. + + +5.1. Default choices and basic rules +If several computation goals are set, all of them are pursued. In particular, computation goals +in the input file and on the command line are accumulated. But +--ignore, -i on the command line switches off the computation goals and algorithmic vari- + ants set in the input file. +The default computation goal is set if neither the input file nor the command line contains +a computation goal or an algorithmic variant that implies a computation goal. The deafault +computatin goal depends on the input type. + • Except the input of a monoid or binomial ideal it is + SupportHyperplanes + HilbertBasis + HilbertSeries . + In the homogeneous case, ClassGroup is included as well. + • For monoid, toric_ideal and normal_toric _ideal it is HilbertBasis + IsIntegrallyClosed + for the momnoid derived from them. + • For the input type lattice_ideal it is MarkovBasis. +If set explicitly in the input file or on the command line the following adds these computation +goals: +DefaultMode +DefaultMode can be set explicitly in addition to other computation goals. If it is set, implicitly + + + + +or explicitly, Normaliz will not complain about unreachable computation goals. + + +5.2. Computation goals +Almost always the computation goals set explicitly or by default require the comoputation of +auxiliary data that themselves can be asked for by explicit computation goals. In most cases +the results of these computations appear in the output. In case of doubt set exlicit computation +goals. + +5.2.1. Lattice data + +Sublattice, -S (upper case S) asks Normaliz to compute the coordinate transformation to + and from the efficient sublattice. + +5.2.2. Support hyperplanes and extreme rays + +SupportHyperplanes, -s triggers the computation of support hyperplanes and extreme rays. +Normaliz tries to find a grading in the homogeneous case. +VerticesFloat converts the format of the vertices to floating point. It implies SupportHyperplanes. + + +SuppHypsFloat converts the format of the support hyperplanes to floating point. It implies + SupportHyperplanes. +ExtremeRaysFloat does the same for the extreme rays. +Note that VerticesFloat and SuppHypsFloat are not pure output options. They are computa- +tion goals, and therefore break implicit DefaultMode. +ProjectCone Normaliz projects the cone defined by the input data onto a subspace generated + by selected coordinate vectors and computes the image with the goal SupportHyperplanes. + +5.2.3. Hilbert basis and lattice points + +HilbertBasis, -N triggers the computation of the Hilbert basis. In inhomogeneous compu- + tations it asks for the Hilbert basis of the recession monoid and the module generators. +WitnessNotIntegrallyClosed, -w With this option, Normaliz stops the Hilbert basis com- + putation as soon it has found a witness confirming that the original monoid is not inte- + grally closed. +Deg1Elements, -1 restricts the computation to the degree 1 elements of the Hilbert basis in + homogeneous computations (where it requires the presence of a grading). +LatticePoints is identical to Deg1Elements in the homogeneous case, but implies NoGradingDenom. + In inhomogeneous computations it is a synonym for HilbertBasis. +SingleLatticePoint stops the computation once a lattice point has been found. Forces the + project-and-lift algorithm. + + + +ModuleGeneratorsOverOriginalMonoid, -M computes a minimal system of generators of + the integral closure over the original monoid (see Section 7.18). Requires the existence + of original monoid generators. +The boolean valued computation goal IsIntegrallyClosed is also related to the Hilbert basis; +see Section 5.2.15. +HilbertBasis ExploitAutomsVectors and +Deg1Elements ExploitAutomsVectors exploit the automorphism group of the cone. + + +5.2.4. Enumerative data + +The computation goals in this section require a grading. They include SupportHyperplanes. +HilbertSeries,-q triggers the computation of the Hilbert series. +EhrhartSeries computes the Ehrhart series of a polytope, regardless of whether it is defined + by homogeneous or inhomogeneous input. In the homogeneous case it is equivalent + to HilbertSeries + NoGradingDenom, but not in the inhomogeneous case. See the + discussion in Section 7.1. Can be combined with HSOP. +Multiplicity, -v restricts the computation to the multiplicity. +Volume, -V computes the lattice normalized and the Euclidean volume of a polytope given + by homogeneous or inhomogeneous input (implies Multiplicity in the homogeneous + case, but also sets NoGradingDenom). +HSOP lets Normaliz compute the degrees in a homogeneous system of parameters and the + induced representation of the Hilbert or Ehrhart series series. Note that HSOP does not + imply HilbertSeries or EhrhartSeries. +NoPeriodBound This option removes the period bound that Normaliz sets for the computation + of the Hilbert quasipolynomial (presently 106 ). +NoQuasiPolynomial suppresses the out put of the quasipolynomial. +NumberLatticePoints finds the number of lattice points. They are not stored. +OnlyCyclotomicHilbSer restricts the output to the series representation with the cyclotomic + denominator. Includes NoQuasiPolynomial. + +5.2.5. Combined computation goals + +Can only be set by single letter command line options: + -n HilbertBasis + Multiplicity + -h HilbertBasis + HilbertSeries + -p Deg1Elements + HilbertSeries + + +5.2.6. The class group + +ClassGroup, -C is self explanatory, includes SupportHyperplanes. Not allowed in inhomo- + geneous computations. + + + +5.2.7. Integer hull + +IntegerHull, -H computes the integer hull of a polyhedron. Implies the computation of the + lattice points in it. +More precisely: in homogeneous computations it implies Deg1Elements, in inhomogeneous +computations it implies HilbertBasis. See Section 2.14. + + +5.2.8. Triangulation and Stanley decomposition + +Triangulation, -T makes Normaliz compute, store and export the full triangulation. +ConeDecomposition, -D Normaliz computes a disjoint decomposition of the cone into semi- + open simplicial cones. Implies Triangulation. +TriangulationSize, -t makes Normaliz count the simplicial cones in the full triangulation. +TriangulationDetSum makes Normaliz additionally sum the absolute values of their deter- + minants. +StanleyDec, -y makes Normaliz compute, store and export the Stanley decomposition. +AllGeneratorsTriangulation makes Normaliz compute and store a triangulation that uses + all generators. +LatticePointTriangulation makes Normaliz compute and store a triangulation that uses all + lattice points in a polytope. +UnimodularTriangulation makes Normaliz compute and store a unimodular triangulation. +The triangulation and the Stanley decomposition are treated separately since they can become +very large and may exhaust memory if they must be stored for output. +Note that these decompositions cannot be computed for a polyhedron that is unbounded (mod- +ulo its maximal subspace). However, they are allowed for polytopes defined by inhomoge- +neous input. UnimodularTriangulation is only allowed in homogeneous computations and +is excluded for algebraic polyhedra. +The following triangulations are defined by the order of the generators. See SEctions 7.15.5 +and 7.15.6. +PlacingTriangulation +PullingTriangulation + + +5.2.9. Face structure + +The f-vector of a polyhedron is computed by +FVector +The set of faces of a polyhedron is computed by +FaceLattice +Like the triangulation or Stanley decomposition the face lattice can become very large, and it +is already computed with FVector. FaceLattice writes an extra output file. The details of its + + + +representation in the extra output file are discussed in Section 7.17. +The face lattice computation is based on the incidence vectors of the facets. It is possible to +retrieve this matrix (independently of FVector or FaceLattice) via the computation goal +Incidence +Section 7.17 as well. See it also for the dual versions +DualFVector +DualFaceLattice +DualIncidence +For computation of orbits we have +FVectorOrbits +FaceLatticeOrbits +DualFVectorOrbits +DualFaceLatticeOrbits + + +5.2.10. Semiopen polyhedra + +IsEmptySemiopen +asks for the emptiness of a semiopen polyhedron. See Section 7.20. + + +5.2.11. Automorphism groups + +Automorphism groups are defined in Section 7.22. +Automorphisms computes the integral automorphisms of rational polyhedra and the algebraic + automorphisms of algebraic polytopes. +RationalAutomorphisms computes the rational automorphisms of rational polytopes. +EuclideanAutomorphisms computes the euclidean automorphisms of rational and algebraic + polytopes. +CombinatorialAutomorphisms computes ate combinatorial automorphisms of polyhedra. +AmbientAutomorphisms computes automorphisms induce by permutations of coordinates of + the ambient space. +InputAutomorphisms computes taional (or algebraic) automorphisms based solely on the in- + put and initial coordinate transformations. + + +5.2.12. Weighted Ehrhart series and integrals + +WeightedEhrhartSeries, -E makes Normaliz compute a generalized Ehrhart series. +VirtualMultiplicity, -L makes Normaliz compute the virtual multiplicity of a weighted + Ehrhart series. +Integral, -I makes Normaliz compute an integral over a polytope. Implies NoGradingDenom. + + + + +These computation goals require a homogeneous computation. +Don’t confuse these options with symmetrization. The latter symmetrizes (if possible) the +given data and uses -E or -L internally on the symmetrized object. The options -E,-I,-L ask +for the input of a polynomial. See Section 4.1.8. + + +5.2.13. Markov and Gröbner bases + +They are discussed in Section 3. +MarkovBasis computes a system of generators for a toric ideal defining a monoid or a lattice + ideal. +GroebnerBasis computes a system of generators for such ideals. +Representations compites the represenztation of the reducible elements in a generating sys- + tem of an affine monoid by the Hilbert basis. + Lex sets the lexicographic monomial order for Gröbner bases, +RevLex sets the degree reverse lexicographic order, +DegLex sets the degree lexicographic order. + + +5.2.14. Local structure + +SingularLocus comoputes the singular locus of an affine monoid (algebra), +CodimSingularLocus computes its codimension. + + +5.2.15. Boolean valued computation goals + +They tell Normaliz to find out the answers to the questions they ask. Two of them are more +important than the others since they may influence the course of the computations: +IsIntegrallyClosed : is the original monoid integrally closed? Normaliz stops the Hilbert + basis computation as soon as it can decide whether the original monoid contains the + Hilbert basis (see Section 2.11.1). Normaliz tries to find the answer as quickly as pos- + sible. This may include the computation of a witness, but not necessarily. If you need a + witness, use WitnessNotIntegrallyClosed, -w. +IsSerreR1 checks the Serre property (R1 ) for ffine monoids (automatically satisfied by nor- + mal monoids). +IsPointed : is the efficient cone C pointed? This computation goal is sometimes useful to + give Normaliz a hint that a nonpointed cone is to be expected. See Section 7.13.3. +For the following we only need the support hyperplanes and the lattice: +IsGorenstein, -G : is the monoid of lattice points Gorenstein? In addition to answering + this question, Normaliz also computes the generator of the interior of the monoid (the + canonical module) if the monoid is Gorenstein. (Only in homogeneous computations.) +The remaining ones: + + + + +IsDeg1ExtremeRays : do the extreme rays have degree 1? (Only in homogeneous computa- + tions.) +IsDeg1HilbertBasis : do the Hilbert basis elements have degree 1? (Only in homogeneous + computations.) +IsReesPrimary : for the input type rees_algebra, is the monomial ideal primary to the irrel- + evant maximal ideal? +IsLatticeIdealToric asks whether the lattice ideal in the input is actually toric +The last three computation goals are not really useful for Normaliz since they will be answered +automatically. Note that they may trigger extensive computations. + + +5.2.16. Fusion rings + +See Appendix H. + + +5.3. Integer type +There is no need to worry about the integer type chosen by Normaliz. All preparatory com- +putations use infinite precision. The main computation is then tried with 64 bit integers. If it +fails, it will be restarted with infinite precision. +Infinite precision does not mean that overflows are completely impossible. In fact, Normaliz +requires numbers of type “degree” fit the type long (typically 64 bit on 64 bit systems). If an +overflow occurs in the computation of such a number, it cannot be remedied. +The amount of computations done with infinite precision is usually very small, but the trans- +formation of the computation results from 64 bit integers to infinite precision may take some +time. If you need the highest possible speed, you can suppress infinite precision completely +by +LongLong +With this option, Normaliz cannot restart a failed computation. LongLong is not a cone prop- +erty. +On the other hand, the 64 bit attempt can be bypassed by +BigInt, -B +Note that Normaliz tries to avoid overflows by intermediate results (even if LongLong is set). +If such overflow should happen, the computation is repeated locally with infinite precision. +(The number of such GMP transitions is shown in the terminal output.) If a final result is too +large, Normaliz must restart the computation globally. +Caveat. The overflow check of Normaliz is not an absolute guarantee. The probability that it +fails is microscopically small, but failure is not totally excluded. Very critical computations +for which one has no other confirmation should be redone in BigInt. +Normaliz tries to improve bases of sublattices by LLL reduction. This is an arithmetically +risky operation, even with BigInt. In case you experience any problems, like a floating point + + + +exception “division by zero”, use +NoLLL +Once it has been used once ro a cone in libnormaliz, it is set for all subsequent computations. +To see the problem just described, run overflow.in with and without NoLLL. + + +5.4. The choice of algorithmic variants +For its main computation goals Normaliz has algorithmic variants. It tries to choose the variant +that seems best for the given input data. This automatic choice may however be a bad one. +Therefore the user can completely control which algorithmic variant is used. + +5.4.1. Primal vs. dual + +For the computation of Hilbert bases Normaliz has two algorithms, the primal algorithm that +is based on triangulations, and the dual algorithm that is of type “pair completion”. We have +seen both in Section 2. Roughly speaking, the primal algorithm is the first choice for generator +input, and the dual algorithm is usually better for constraints input. The choice also applies to +the computation of degree 1 elements. However, for them the default choice is project-and-lift +(well, almost always). See Section 7.2.1. The conditions under which the dual algorithm is +chosen are specified in Section 7.5. +The choice of the algorithm can be fixed or blocked: +DualMode, -d activates the dual algorithm for the computation of the Hilbert basis and de- + gree 1 elements. Includes HilbertBasis, unless Deg1Elements is set. It overrules + IsIntegrallyClosed. +PrimalMode, -P blocks the use of the dual algorithm. +The automatic choice can of course fail. See Section 7.5 for an example for which it is bad. + +5.4.2. Lattice points in polytopes + +For this task Normaliz has several methods. They are discussed in Section 7.2. The default +choice is the project-and-lift algorithm. It can be chosen explicitly: +Projection, -j +NoProjection blocks it. +Alternative choices are +ProjectionFloat, -J , project-and-lift with floating point arithmetic, +PrimalMode, -P , triangulation based method, +Approximate, -r , approximation of rational polytopes followed by triangulation and +DualMode, -d , dual algorithm. +Note: none of these algorithmic variants implies the computation of the lattice points. They +must be asked for by a computation goal. + + + +The following options modify Projection and ProjectionFloat: +NoLLL blocks the use of LLL reduced coordinates, +NoRelax blocks relaxation. +Both LLL and relaxation are switched on by default. See Section 7.2.3. +For positive systems (see Section 7.2.4) Normaliz chooses “coarse projection”, and it may use +a patching variant of project-and-lift. These choices can be blocked by +NoCoarseProjection +NoPatching +Moreover, there are further options by which the order, in which the “patches” are processed, +can be influenced. See Section 7.2.6. + + +5.4.3. Bottom decomposition and order + +Bottom decomposition is a way to produce an optimal triangulation for a given set of genera- +tors. It is discussed in Section 7.3. The criterion for its automatic choice is explained there. It +can be forced or blocked: +BottomDecomposition, -b tells Normaliz to use bottom decomposition in the primal algo- + rithm. +NoBottomDec, -o forbids Normaliz to use bottom decomposition in the primal algorithm, + even if it would otherwise be chosen because of large roughness (see Section 7.3). +An option to be mentioned in this context is +KeepOrder, -k forces Normaliz to insert the generators (for generator input) or the inequal- + ities (for constraint input) in the input order. This option is useful if the input has been + produced in a systematic order that would be destroyed by the degree-lexicogrpahic + order applied by Normaliz. Also blocks BottomDecomposition. + + +5.4.4. Multiplicity, volume and integrals + +For the computation of multiplicities Normaliz offers has three main algorithms: + (1) the computation and evaluation of a full triangulation, + (2) descent in the face lattice, + (3) signed decomposition. +These are described in more detail in Section 7.6. Moreover, one can use symmetrization (see +below), and (2) has a variant using isomorphism types. +Normaliz tries them by default in the order signed decoposition, descent, symmetritation and +uses the first for which the default conditions are satisfied (as long as there is no need to +compute a full triangulation for other reasons). The last resort is (1). +The options asking explicitly for an algorithm or excluding it are +Descent, -F + + + + +NoDescent +SignedDec +NoSignedDec +The variant using isomorphism types can be activated by +Descent ExploitIsosMult +You van ask for +StrictTypeChecking +if you don’t btrust SHA256 hash values. See Section 7.6.3. +Another option to be mentioned in this context is +FixedPrecision +It can be applied if the multiplicity is computed by signed decomposition. See Section 7.6.5 +For integrals one can chose either the standard triangulation or signed decomposition. In the +latter case FixedPrecision is also available. +If one wants to compute multiplicities (or volumes) with signed decomposition, one can use +distributed computation on a HPC. Distributed computation is described in Appendix F.1. + + +5.4.5. Symmetrization + +In rare cases Normaliz can use symmetrization in the computation of multiplicities or Hilbert +series. If applicable, this is a very strong tool. We have mentioned it in Section 2.10 and will +discuss it in Section 7.8. It will be chosen automatically, but can also be forced or blocked: +Symmetrize, -Y lets Normaliz compute the multiplicity and/or the Hilbert series via sym- + metrization (or just compute the symmetrized cone). +NoSymmetrization blocks symmetrization. +The integration involved in symmetrization can be done by signed decomposition. + + +5.4.6. Options for the grading + +By setting +NoGradingDenom +you can force Normaliz not to change the original grading if it would otherwise divide it +by the grading denominator. It is implied by several computation goals for polytopes. See +Section 7.1. +NoGradingDenom is set automatically inn inhomogeneous computations. +By +GradingIsPositive +the user guarantees that the grading is positive. This option can be useful in rare cases if +Normaliz would otherwise compute extreme rays only to check the positivity of the grading. + + + +5.5. Control of computations and communication with interfaces +In addition to the computation goals in Section 5.2, the following elements of ConeProperties +control the work flow in libnormaliz and can be used by programs calling Normaliz to ensure +the availability of the data that are controlled by them. +OriginalMonoidGenerators controls the generators of the original monoid. +ModuleGenerators controls the module generators in inhomogeneous computation. +ExtremeRays controls the extreme rays. +VerticesOfPolyhedron controls the vertices of the polyhedron in the inhomogeneous case. +MaximalSubspace controls the maximal linear subspace of the (homogenized) cone. +EmbeddingDim controls the embedding dimension. +Rank controls the rank. +RecessionRank controls the rank of the recession monoid in inhomogeneous computations. +AffineDim controls the affine dimension of the polyhedron in inhomogeneous computations. +ModuleRank in inhomogeneous computations it controls the rank of the module of lattice + points in the polyhedron as a module over the recession monoid. +ExcludedFaces controls the excluded faces. +InclusionExclusionData controls data derived from the excluded faces. +Grading controls the grading. +GradingDenom controls its denominator. +Dehomogenization controls the dehomogenization. +ReesPrimaryMultiplicity controls the multiplicity of a monomial ideal, provided it is pri- + mary to the maximal ideal generated by the indeterminates. Used only with the input + type rees_algebra. +EuclideanVolume controls the Euclidean volume. +GeneratorOfInterior controls the generator of the interior if the monoid is Gorenstein. +CoveringFace asks for an excluded face making the semiopen polyhedron empty. +Equations controls the equations. +Congruences controls the congruences. +ExternalIndex controls the external index. +InternalIndex controls the internal index. +UnitGroupIndex controls the unit group index. +IsInhomogeneous controls the inhomogeneous case. +HilbertQuasiPolynomial controls the Hilbert quasipolynomial. +EhrhartQuasiPolynomial controls the Ehrhart quasipolynomial. +WeightedEhrhartQuasiPolynomial controls the weighted Ehrhart quasipolynomial. +IsTriangulationNested controls the indicator of this property. +IsTriangulationPartial similar. +NoSubdivision blocks pyramid decomposition and sudivision of simplices in primal mode. +BasicTriangulation used for the computation of trianglations. itemtt[BasicStanleyDec] the + same for Stanley decompositions. +PullingTriangulationInternal used for the computation of pulling triangulations. + + + + +SingleLatticePointInternal quite obvious. + + + +5.6. Rational and integer solutions in the inhomogeneous case +The integer solutions of a homogeneous diophantine system generate the rational solutions as +well: every rational solution has a multiple that is an integer solution. Therefore the rational +solutions do not need an extra computation. If you prefer geometric language: a rational cone +is generated by its lattice points. +This is no longer true in the inhomogeneous case where the computation of the rational solu- +tions is an extra task for Normaliz. This extra step is inevitable for the primal algorithm, but +not for the dual algorithm. In general, the computation of the rational solutions is much faster +than the computation of the integral solutions, but this by no means always the case. +Therefore we have decoupled the two computations if the dual algorithm is applied to inho- +mogeneous systems or to the computation of degree 1 points in the homogeneous case. The +combinations +DualMode HilbertBasis, -dN +DualMode Deg1Elements, -d1 +DualMode ModuleGenerators +DualMode LatticePoints +do not imply the computation goal SupportHyperplanes (and not even Sublattice) which +would trigger the computation of the rational solutions (geometrically: the vertices of the +polyhedron). If you want to compute them, you must add one of +SupportHyperplanes, -s +ExtremeRays +VerticesOfPolyhedron +The last choice is only possible in the inhomogeneous case. Another possibility in the inho- +mogeneous case is is to use DualMode without a restriction. +If Projection or ProjectionFloat is used for parallelotopes defined by inequalities, then +Normaliz does not compute the vertices, unless asked for by one of the three computation +goals just mentioned or the extreme rays are needed for some other computation. The same +holds if the volume of a parallelotope is computed. + + +6. Running Normaliz +The standard form for calling Normaliz is + normaliz [options] +where is the name of the project, and the corresponding input file is .in. +Note that normaliz may require to be prefixed by a path name, and the same applies to +. A typical example on a Linux or Mac system: + + + + + ./normaliz --verbose -x=5 example/big +that for MS Windows must be converted to + .\normaliz --verbose -x=5 example\big +Normaliz uses the standard conventions for calls from the command line: + (1) the order of the arguments on the command line is arbitrary. + (2) Single letter options are prefixed by the character - and can be grouped into one string. + (3) Verbatim options are prefixed by the characters --. +The options for computation goals and algorithmic variants have been described in Section 5. +In this section the remaining options for the control of execution and output are discussed, +together with some basic rules for the use of the options. + + +6.1. Basic rules +The options for computation goals and algorithms variants have been explained in Section 5. +The options that control the execution and the amount of output will be explained in the +following. Basic rules for the use of options: + 1. If no is given, the program will terminate. + 2. The option -x differs from the other ones: in -x= represents a positive number + assigned to -x; see Section 6.3. + 3. Similarly the option --OutputDir= sets the output directory; see 6.7. + 4. Normaliz will look for .in as input file. + If you inadvertently typed rafa2416.in as the project name, then Normaliz will first + look for rafa2416.in.in as the input file. If this file doesn’t exist, rafa2416.in will be + loaded. + 5. The options can be given in arbitrary order. All options, including those in the input + file, are accumulated, and syntactically there is no mutual exclusion. However, some + options may block others during the computation. For example, KeepOrder blocks + BottomDecomposition. + 6. If Normaliz cannot perform a computation explicitly asked for by the user, it will termi- + nate. Typically this happens if no grading is given although it is necessary. + 7. In the options include DefaultMode, Normaliz does not complain about missing data + (anymore). It will simply omit those computations that are impossible. + 8. If a certain type of computation is not asked for explicitly, but can painlessly be produced + as a side effect, Normaliz will compute it. For example, as soon as a grading is present + and the Hilbert basis is computed, the degree 1 elements of the Hilbert basis are selected + from it. + In addition to computing a single file per run, Normaliz can also process a list of input + files. See Section G. + + + + +6.2. Info about Normaliz +--help, -? displays a help screen listing the Normaliz options. +--version displays information about the Normaliz executable. + + + +6.3. Control of execution +The options that control the execution are: +--verbose, -c activates the verbose (“console”) behavior of Normaliz in which Normaliz + writes additional information about its current activities to the standard output. +--talk gives more output than verbose (at present only implemented in the patching variant + of project-and-lift) +-x= Here stands for a positive integer limiting the number of threads that Normaliz is + allowed access on your system. The default value is 8. (Your operating system may set + a lower limit). + -x=0 switches off the limit set by Normaliz. + If you want to run Normaliz in a strictly serial mode, choose -x=1. +parallel_threads can be used in the input file instead. +The number of threads can also be controlled by the environment variable OMP_NUM_THREADS. +See Section 10.1 for further discussion. +If there ar5e many polynomials in the input it can be difficult to find an error in them. As a +help ion such cases one can say +list_polynomials +The last polynomial listed has caused the error. + + +6.4. Interruption +During a computation normaliz can be interrupted by pressing Ctrl-C on the keyboard. If this +happens, Normaliz will stop the current computation. If you want to see the results already +computed, ask for +OutputOnInterrupt, --OOU +Can be set in the input file or on the command line as a long option. +If Ctrl-C is pressed during the output phase, Normaliz is stopped immediately. + + +6.5. Stopping a computation +If Normaliz is running in the background and cannot be interrupted by CTrl-C, then one can +stop it by inserting a file +normaliz.stop + + + + +into the working directory. This will stop (possibly with some delay) the instances of normaliz +running in that directory. In order to stop a specific instance, use +.stop + + + +6.6. Time bound +In order to set a time bound for the execution of Normaliz one creates a file +normaliz.time +in the working directory. It contains a single floating number that bounds the wall clock time +of Normaliz. At present it is only implemented in the project-and-lift algorithm for lattice +points. + + +6.7. Control of output files +In the default setting Normaliz writes only the output file .out (and the files pro- +duced by Triangulation, StanleyDec and FaceLattice). The amount of output files can be +increased as follows: +--files, -f Normaliz writes the additional output files with suffixes gen, cst, and inv, pro- + vided the data of these files have been computed. +--all-files, -a includes Files, Normaliz writes all available output files (except typ and + those that are automatically written by computation goals). +-- chooses the output file with suffix . +For the list of potential output files, their suffixes and their interpretation see Section 9. There +are several options --. +If the computation goal IntegerHull is set, Normaliz computes a second cone and lattice. +The output is contained in .IntHull.out. The options for the output of +are applied to .IntHull as well. There is no way to control the output of the two +computations individually. +Similarly, if symmetrization has been used, Normaliz writes the file .symm.out. It +contains the data of the symmetrized cone. +Sometimes one wants the output to be written to another directory. The output directory can +be set by +--OutputDir= . The path is an absolute path or a path relative to the + current directory (which is not necessarily the directory of .in.) +Note that all output files will be written to the chosen directory. It must be created before +Normaliz is started. +Extreme rays and vertices may have very long integer coordinates. One can suppress their +output by +NoExtRaysOutput + + + + +For similar reasons one may want to suppress the output of support hyperplanes, namely by +NoSuppHypsOutput +Similarly, +NoHilbertBasisOutput +supprsesses thze output of Hilbert bases and latticec points. An even more drastic option is +NoMatricesOutput +It suppresses all output after the “preamble”. It is useful in testing large examples where the +numbers of extreme rays, lattice points etc. are usually a good criterion for correctness. +NoExtRaysOutput, NoSuppHypsOutputand NoMatricesOutput are not cone properties. +BinomialsPacked chooses a packed format for files containing binomials. See Section 7.25. + + + +6.8. Ignoring the options in the input file +Since Normaliz accumulates options, one cannot get rid of settings in the input file by com- +mand line options unless one uses +--ignore, -i This option disables all options in the input file. + + + + diff --git a/apn/lean/docs/ore_algebra/LICENSE b/apn/lean/docs/ore_algebra/LICENSE new file mode 100644 index 00000000..d159169d --- /dev/null +++ b/apn/lean/docs/ore_algebra/LICENSE @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/apn/lean/docs/ore_algebra/ore_algebra.md b/apn/lean/docs/ore_algebra/ore_algebra.md new file mode 100644 index 00000000..28e2de11 --- /dev/null +++ b/apn/lean/docs/ore_algebra/ore_algebra.md @@ -0,0 +1,1709 @@ + + +# ore_algebra (Sage package) + +Ore algebra +============ + +https://github.com/mkauers/ore_algebra/ + +Description +----------- + +A Sage implementation of Ore algebras, Ore polynomials, and differentially +finite functions + +Main features for the most common algebras include basic arithmetic and actions; +gcrd and lclm; D-finite closure properties; creative telescoping; natural +transformations between related algebras; guessing; desingularization; solvers +for polynomials, rational functions and (generalized) power series. Univariate +differential operators also support the numerical computation of analytic +solutions with rigorous error bounds and related features. + + + +## Module `ore_algebra` — constructing Ore algebras + +Ore algebras + +The ``ore_algebra`` package provides functionality for doing computations with Ore polynomials. + +Ore polynomials are operators which can be used to describe special functions or combinatorial +sequences. Typical examples are linear differential operators with polynomial coefficients. + +Ore polynomials are elements of Ore algebras. Ore algebras are ring objects created by the +function ``OreAlgebra`` as described below. + +Depending on the particular parent algebra, Ore polynomials may support different functionality. +For example, for Ore polynomials representing recurrence operators, there is a method for +computing interlacing operators, an operation which does not make sense for differential operators. + +The typical user will only need two functions defined in the package: + + * ``OreAlgebra`` -- for creating a new Ore algebra object. + * ``guess`` -- for fitting an Ore polynomial to a given set of data. + +Ore polynomials are created using ``OreAlgebra`` objects, and most of the functionality for +doing calculations with Ore polynomials is available in the methods attached to them. + +For examples and further information, see the docstring of ``OreAlgebra`` below, or the +tutorial paper *Ore Polynomials in Sage* by the authors. + + +AUTHOR: + +- Manuel Kauers, Maximilian Jaroschek, Fredrik Johansson (2013-06-15) + +### `OreAlgebra` + +``` +An Ore algebra is a noncommutative polynomial ring whose elements are +interpreted as operators. + +An Ore algebra has the form `A=R[\partial_1,\partial_2,\dots,\partial_n]` +where `R` is an integral domain and `\partial_1,\dots,\partial_n` are +indeterminates. For each of them, there is an associated automorphism +`\sigma:R\\rightarrow R` and a skew-derivation `\delta:R\\rightarrow R` +satisfying `\delta(a+b)=\delta(a)+\delta(b)` and +`\delta(ab)=\delta(a)b+\sigma(a)\delta(b)` for all `a,b\in R`. + +The generators `\partial_i` commute with each other, but not with elements +of the base ring `R`. Instead, we have the commutation rules `\partial u = +\sigma(u) \partial + \delta(u)` for all `u\in R`. + +The base ring `R` must be suitable according to the following definition: +`ZZ`, `QQ`, `GF(p)` for primes `p`, and finite algebraic extensions of `QQ` +are suitable, and if `R` is suitable then so are `R[x]`, `R[x_1,x_2,...]` +and `Frac(R)`. It is assumed that all the `\sigma` leave ``R.base_ring()`` fixed +and all the `\delta` map ``R.base_ring()`` to zero. + +A typical example of an Ore algebra is the ring of linear differential +operators with rational function coefficients in one variable, +e.g. `A=QQ[x][D]`. Here, `\sigma` is the identity and `\delta` is the +standard derivation `d/dx`. + +To create an Ore algebra, supply a suitable base ring and one or more +generators. Each generator has to be given in form of a triple +``(name,sigma,delta)`` where ``name`` is the desired name of the variable +(used for printout), ``sigma`` and ``delta`` are arbitrary callable objects +which applied to the base ring return other base ring elements in accordance +with the relevant laws. It is not checked whether they do. + +:: + + sage: from ore_algebra import * + + sage: R. = QQ['x'] + sage: K = R.fraction_field() + + # This creates an Ore algebra of linear differential operators + sage: A. = OreAlgebra(K, ('D', lambda p: p, lambda p: p.derivative(x))) + sage: A + Univariate Ore algebra in D over Fraction Field of Univariate Polynomial Ring in x over Rational Field + + # This creates an Ore algebra of linear recurrence operators + sage: A. = OreAlgebra(K, ('S', lambda p: p(x+1), lambda p: K.zero())) + sage: A + Univariate Ore algebra in S over Fraction Field of Univariate Polynomial Ring in x over Rational Field + +Instead of a callable object for `\sigma` and `\delta`, also a dictionary can +be supplied which for every generator of the base ring specifies the desired +image. If some generator is not in the dictionary, it is understood that +`\sigma` acts as identity on it, and that `\delta` maps it to zero. + +:: + + sage: U. = ZZ['x', 'y'] + + # here, the base ring represents the differential field QQ(x, e^x) + sage: A. = OreAlgebra(U, ('D', {}, {x:1, y:y})) + + # here, the base ring represents the difference field QQ(x, 2^x) + sage: B. = OreAlgebra(U, ('S', {x:x+1, y:2*y}, {})) + + # here too, but the algebra's generator represents the forward difference instead of the shift + sage: C. = OreAlgebra(U, ('Delta', {x:x+1, y:2*y}, {x:1, y:y})) + +For the most frequently needed operators, the constructor accepts their +specification as a string only, without explicit statement of sigma or +delta. The string has to start with one of the letters listed in the +following table. The remainder of the string has to be the name of one +of the generators of the base ring. The operator will affect this generator +and leave the others untouched. + + ============= ======================= ================ ============= + Prefix Operator `\sigma` `\delta` + ============= ======================= ================ ============= + C Commutative variable `\{\}` `\{\}` + D Standard derivative `\{\}` `\{x:1\}` + S Standard shift `\{x:x+1\}` `\{\}` + \u0394, F Forward difference `\{x:x+1\}` `\{x:1\}` + \u03B8, T, E Euler derivative `\{\}` `\{x:x\}` + Q q-shift `\{x:q*x\}` `\{\}` + J Jackson's q-derivative `\{x:q*x\}` `\{x:1\}` + ============= ======================= ================ ============= + +In the case of C, the suffix need not be a generator of the ground field but +may be an arbitrary string. In the case of Q and J, either the base ring has +to contain an element `q`, or the base ring element to be used instead has to +be supplied as optional argument. + +:: + + sage: R. = QQ['x', 'y'] + sage: A = OreAlgebra(R, 'Dx') # This creates an Ore algebra of differential operators + sage: A == OreAlgebra(R, ('Dx', {}, {x:1})) + True + sage: A == OreAlgebra(R, ('Dx', {}, {y:1})) # the Dx in A acts on x, not on y + False + + # This creates an Ore algebra of linear recurrence operators + sage: A = OreAlgebra(R, 'Sx') + sage: A == OreAlgebra(R, ('Sx', {x:x+1}, {})) + True + sage: A == OreAlgebra(R, ('Sx', {y:y+1}, {})) # the Sx in A acts on x, not on y + False + sage: OreAlgebra(R, 'Qx', q=2) + Univariate Ore algebra in Qx over Multivariate Polynomial Ring in x, y over Rational Field + +A generator can optionally be extended by a vector `(w_0,w_1,w_2)` of +base ring elements which encodes the product rule for the generator: +`D(u*v) == w_0*u*v + w_1*(D(u)*v + u*D(v)) + w_2*D(u)*D(v)`. This data +is needed in the computation of symmetric products. + +Ore algebras support coercion from their base rings. Furthermore, an Ore +algebra `A` knows how to coerce commutative polynomials `p` to elements of +`A` if the generators of the parent of `p` have the same names as the +generators of `A`, and the base ring of the parent of `p` admits a coercion +to the base ring of `A`. The ring of these polynomials is called the +associated commutative algebra of `A`, and it can be obtained by calling +``A.associated_commutative_algebra()``. + +Elements of Ore algebras are called Ore operators. They can be constructed +from the same data from which also elements of the associated commutative +algebra can be constructed. + +The conversion from data to an Ore operator is equivalent to the conversion +from the given data to an element of the associated commutative algebra, and +from there to an Ore operator. This has the consequence that possible implicit +information about multiplication order may be lost, for example when generating +operators from strings: + +:: + + sage: A = OreAlgebra(QQ['x'], 'Dx') + sage: A("Dx*x") + x*Dx + sage: A("Dx")*A("x") + x*Dx + 1 + +A safer way of creating operators is via a list of coefficients. These are then +always interpreted as standing to the left of the respective algebra generator monomial. + +:: + + sage: R. = QQ['x'] + sage: A. = OreAlgebra(R, 'Dx') + sage: A([x^2+1, 5*x-7, 7*x+18]) + (7*x + 18)*Dx^2 + (5*x - 7)*Dx + x^2 + 1 + sage: (7*x + 18)*Dx^2 + (5*x - 7)*Dx + x^2 + 1 + (7*x + 18)*Dx^2 + (5*x - 7)*Dx + x^2 + 1 + sage: _^2 + (49*x^2 + 252*x + 324)*Dx^4 + (70*x^2 + 180*x)*Dx^3 + (14*x^3 + 61*x^2 + 49*x + 216)*Dx^2 + (10*x^3 + 14*x^2 + 107*x - 49)*Dx + x^4 + 12*x^2 + 37 + + sage: R. = QQ['x'] + sage: A. = OreAlgebra(QQ['x'], 'Sx') + sage: A([x^2+1, 5*x-7, 7*x+18]) + (7*x + 18)*Sx^2 + (5*x - 7)*Sx + x^2 + 1 + sage: (7*x + 18)*Sx^2 + (5*x - 7)*Sx + x^2 + 1 + (7*x + 18)*Sx^2 + (5*x - 7)*Sx + x^2 + 1 + sage: _^2 + (49*x^2 + 350*x + 576)*Sx^4 + (70*x^2 + 187*x - 121)*Sx^3 + (14*x^3 + 89*x^2 + 69*x + 122)*Sx^2 + (10*x^3 - 4*x^2 + x - 21)*Sx + x^4 + 2*x^2 + 1 + +It is possible to bypass the check that the base ring is suitable, but doing so +may lead to mathematically incorrect results. Only use this if you know exactly +what you are doing! :: + + sage: R. = SR[] + sage: Dop. = OreAlgebra(R, check_base_ring=False) + sage: (Dx - pi*x)^2 + Dx^2 - 2*pi*x*Dx + pi^2*x^2 - pi +``` + + +### `DifferentialOperators` + +``` +Shorthand to construct an Ore algebra of differential operators. + +Return an Ore algebra of differential operators with polynomial +coefficients, along with objects representing, x and d/dx. + +.. SEEALSO:: :func:`OreAlgebra` + +INPUT: + +* ``base`` (default ``QQ``) - base ring of the polynomial coefficients +* ``var`` (default ``x``) - variable name + +EXAMPLES:: + + sage: from ore_algebra import * + sage: Dops, x, Dx = DifferentialOperators() + sage: Dops + Univariate Ore algebra in Dx over Univariate Polynomial Ring in x over + Rational Field + sage: x*Dx + 1 + x*Dx + 1 + + sage: DifferentialOperators(GF(2), 't') + (Univariate Ore algebra in Dt over Univariate Polynomial Ring in t over + Finite Field of size 2 (...), + t, Dt) +``` + + +## Module `ore_algebra.guessing` + +Guessing tools + +TESTS:: + + sage: from ore_algebra import OreAlgebra, guess + sage: guess([SR(1/(i+1)) for i in range(10)], OreAlgebra(QQ['n'], 'Sn')) + (-n - 2)*Sn + n + 1 + +### `guess_rec` + +``` +Shortcut for ``guess`` applied with an Ore algebra of shift operators in `S` over `K[n]` +where `K` is the parent of ``data[0]``. + +See the docstring of ``guess`` for further information. +``` + + +### `guess_deq` + +``` +Shortcut for ``guess`` applied with an Ore algebra of differential operators in `D` over `K[x]` +where `K` is the parent of ``data[0]``. + +See the docstring of ``guess`` for further information. +``` + + +### `guess_qrec` + +``` +Shortcut for ``guess`` applied with an Ore algebra of `q`-recurrence operators in `Q` over `K[qn]` +where `K` is the parent of `q`. + +See the docstring of ``guess`` for further information. +``` + + +### `guess` + +``` +Searches for an element of the algebra which annihilates the given data. + +INPUT: + +- ``data`` -- a list of elements of the algebra's base ring's base ring `K` (or at least + of objects which can be casted into this ring). If ``data`` is a string, it is assumed + to be the name of a text file which contains the terms, one per line, encoded in a way + that can be interpreted by the element constructor of `K`. +- ``algebra`` -- a univariate Ore algebra over a univariate polynomial ring whose + generator is the standard derivation, the standard shift, the forward difference, + a q-shift, or a commutative variable. + +Optional arguments: + +- ``cut`` -- if `N` is the minimum number of terms needed for some particular + choice of order and degree, and if ``len(data)`` is more than ``N+cut``, + use ``data[:N+cut]`` instead of ``data``. This must be a nonnegative integer + or ``None``. Default: ``None``. +- ``ensure`` -- if `N` is the minimum number of terms needed for some particular + choice of order and degree, and if ``len(data)`` is less than ``N+ensure``, + raise an error. This must be a nonnegative integer. Default: 0. +- ``ncpus`` -- number of processors to be used. Default: 1. +- ``order`` -- bounds the order of the operators being searched for. + Default: infinity. +- ``min_order`` -- smallest order to be considered in the search. The output + may nevertheless have lower order than this bound. Default: 1 +- ``degree`` -- bounds the degree of the operators being searched for. + The method may decide to overrule this setting if it thinks this may speed up + the calculation. Default: infinity. +- ``min_degree`` -- smallest degree to be considered in the search. The output + may nevertheless have lower degree than this bound. Default: 0 +- ``path`` -- a list of pairs `(r, d)` specifying which orders and degrees + the method should attempt. If this value is equal to ``None`` (default), a + path is chosen which examines all the `(r, d)` which can be tested with the + given amount of data. +- ``solver`` -- function to be used for computing the right kernel of a matrix + with elements in `K`. +- ``infolevel`` -- an integer specifying the level of details of progress + reports during the calculation. +- ``method`` -- either "linalg" (for linear algebra) or "hp" (for Hermite-Pade) or "automatic" + (for the default choice), or a callable with the specification of a raw guesser. + +OUTPUT: + +- An element of ``algebra`` which annihilates the given ``data``. + +An error is raised if no such element is found. + +.. NOTE:: + + - This method is designed to find equations for D-finite objects. It + may exhibit strange behaviour for objects which are holonomic but not + D-finite. + - When the generator of the algebra is a commutative variable, the + method searches for algebraic equations. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: rec = guess([(2*i+1)^15 * (1 + 2^i + 3^i)^2 for i in range(1000)], OreAlgebra(ZZ['n'], 'Sn')) # long time (2.9 s) + sage: rec.order(), rec.degree() # long time + (6, 90) + sage: R. = QQ['t'] + sage: rec = guess([1/(i+t) + t^i for i in range(100)], OreAlgebra(R['n'], 'Sn')) + sage: rec + ((-t + 1)*n^2 + (-2*t^2 - t + 2)*n - t^3 - 2*t^2)*Sn^2 + ((t^2 - 1)*n^2 + (2*t^3 + 3*t^2 - 2*t - 1)*n + t^4 + 3*t^3 + t^2 - t)*Sn + (-t^2 + t)*n^2 + (-2*t^3 + t)*n - t^4 - t^3 + t^2 + + sage: R. = OreAlgebra(ZZ['x']) + sage: cat = [binomial(2*n,n) // (n+1) for n in range(10)] + sage: guess(cat, R) + -x*C^2 + C - 1 +``` + + +### `guess_raw` + +``` +Guesses recurrence or differential equations for a given sample of terms. + +INPUT: + +- ``data`` -- list of terms +- ``A`` -- an Ore algebra of recurrence operators, differential operators, + or q-differential operators. +- ``order`` -- maximum order of the sought operators +- ``degree`` -- maximum degree of the sought operators +- ``lift`` (optional) -- a function to be applied to the terms in ``data`` + prior to computation +- ``solver`` (optional) -- a function to be used to compute the nullspace + of a matrix with entries in the base ring of the base ring of ``A`` +- ``cut`` (optional) -- if `N` is the minimum number of terms needed for + the the specified order and degree and ``len(data)`` is more than ``N+cut``, + use ``data[:N+cut]`` instead of ``data``. This must be a nonnegative integer + or ``None``. +- ``ensure`` (optional) -- if `N` is the minimum number of terms needed + for the specified order and degree and ``len(data)`` is less than ``N+ensure``, + raise an error. This must be a nonnegative integer. +- ``infolevel`` (optional) -- an integer indicating the desired amount of + progress report to be printed during the calculation. Default: 0 (no output). + +OUTPUT: + +A basis of the ``K``-vector space of all the operators `L` in ``A`` of order +at most ``order`` and degree at most ``degree`` such that `L` applied to +``data`` gives an array of zeros. (resp. `L` applied to the truncated power +series with ``data`` as terms gives the zero power series) + +An error is raised in the following situations: + +* the algebra ``A`` has more than one generator, or its unique generator + is neither a standard shift nor a q-shift nor a standard derivation. +* ``data`` contains some item which does not belong to ``K``, even after + application of ``lift`` +* if the condition on ``ensure`` is violated. +* if the linear system constructed by the method turns out to be + underdetermined for some other reason, e.g., because too many linear + constraints happen to be trivial. + +ALGORITHM: + +Ansatz and linear algebra. + +.. NOTE:: + + This is a low-level method. Don't call it directly unless you know what you + are doing. In usual applications, the right method to call is ``guess``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: K = GF(1091); R. = K['n']; A = OreAlgebra(R, 'Sn') + sage: data = [(5*n+3)/(3*n+4)*fibonacci(n)^3 for n in range(200)] + sage: guess_raw(data, A, order=5, degree=3, lift=K) + [(n^3 + 546*n^2 + 588*n + 786)*Sn^5 + (356*n^3 + 717*n^2 + 381*n + 449)*Sn^4 + (8*n^3 + 569*n^2 + 360*n + 214)*Sn^3 + (31*n^3 + 600*n^2 + 784*n + 287)*Sn^2 + (1078*n^3 + 1065*n^2 + 383*n + 466)*Sn + 359*n^3 + 173*n^2 + 503, (n^3 + 1013*n^2 + 593*n + 754)*Sn^5 + (797*n^3 + 56*n^2 + 7*n + 999)*Sn^4 + (867*n^3 + 1002*n^2 + 655*n + 506)*Sn^3 + (658*n^3 + 834*n^2 + 1036*n + 899)*Sn^2 + (219*n^3 + 479*n^2 + 476*n + 800)*Sn + 800*n^3 + 913*n^2 + 280*n] +``` + + +### `guess_hp` + +``` +Guesses differential equations or algebraic equations for a given sample of terms. + +INPUT: + +- ``data`` -- list of terms +- ``A`` -- an Ore algebra of differential operators or ordinary polynomials. +- ``order`` -- maximum order of the sought operators +- ``degree`` -- maximum degree of the sought operators +- ``lift`` (optional) -- a function to be applied to the terms in ``data`` + prior to computation +- ``cut`` (optional) -- if `N` is the minimum number of terms needed for + the the specified order and degree and ``len(data)`` is more than ``N+cut``, + use ``data[:N+cut]`` instead of ``data``. This must be a nonnegative integer + or ``None``. +- ``ensure`` (optional) -- if `N` is the minimum number of terms needed + for the specified order and degree and ``len(data)`` is less than ``N+ensure``, + raise an error. This must be a nonnegative integer. +- ``infolevel`` (optional) -- an integer indicating the desired amount of + progress report to be printed during the calculation. Default: 0 (no output). + +OUTPUT: + +A basis of the ``K``-vector space of all the operators `L` in ``A`` of order +at most ``order`` and degree at most ``degree`` such that `L` applied to +the truncated power series with ``data`` as terms gives the zero power series. + +An error is raised in the following situations: + +* the algebra ``A`` has more than one generator, or its unique generator + is neither a standard derivation nor a commutative variable. +* ``data`` contains some item which does not belong to ``K``, even after + application of ``lift`` +* if the condition on ``ensure`` is violated. + +ALGORITHM: + +Hermite-Pade approximation. + +.. NOTE:: + + This is a low-level method. Don't call it directly unless you know what you + are doing. In usual applications, the right method to call is ``guess``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: from ore_algebra.guessing import guess_hp + sage: K = GF(1091); R. = K['x']; + sage: data = [binomial(2*n, n)*fibonacci(n)^3 for n in range(2000)] + sage: guess_hp(data, OreAlgebra(R, 'Dx'), order=4, degree=4, lift=K) + [(x^4 + 819*x^3 + 136*x^2 + 17*x + 635)*Dx^4 + (14*x^3 + 417*x^2 + 952*x + 605)*Dx^3 + (598*x^2 + 497*x + 99)*Dx^2 + (598*x + 794)*Dx + 893] + sage: len(guess_hp(data, OreAlgebra(R, 'C'), order=16, degree=64, lift=K)) + 1 +``` + + +### `guess_mult` + +``` +Searches for elements of the algebra which annihilates the given data. + +INPUT: + +- ``data`` -- a nested list of elements of the algebra's base ring's base ring `K` (or at least + of objects which can be casted into this ring). + The depth of the nesting must match the number of generators of the algebra. +- ``algebra`` -- an Ore algebra over a polynomial ring all of whose generators are + the standard derivation, the standard shift, or a q-shift. + +Optional arguments: + +- ``cut`` -- if `N` is the minimum number of terms needed for some particular + choice of order and degree, and if ``len(data)`` is more than ``N+cut``, + use ``data[:N+cut]`` instead of ``data``. This must be a nonnegative integer + or ``None``. Default: 100. +- ``ensure`` -- if `N` is the minimum number of terms needed for some particular + choice of order and degree, and if ``len(data)`` is less than ``N+ensure``, + raise an error. This must be a nonnegative integer. Default: 0. +- ``order`` -- maximum degree of the algebra generators in the sought operators. + Alternatively: a list or tuple specifying individual degree bounds for each + generator of the algebra. Default: 2 +- ``degree`` -- maximum total degree of the polynomial coefficients in the sought + operators. Default: 3 +- ``point_filter`` -- a callable such that index tuples of data array for which + the callable returns 'False' will not be used. Default: None (everything allowed). +- ``term_filter`` -- a callable such that operators containing power products of + the algebra generators for which the callable returns 'False' are excluded. + Default: None (everything allowed). +- ``solver`` -- function to be used for computing the right kernel of a matrix + with elements in `K`. +- ``infolevel`` -- an integer specifying the level of details of progress + reports during the calculation. + +OUTPUT: + +- The left ideal of ``algebra`` generated by all the operators of the specified order and degree + that annihilate the given ``data``. It may be the zero ideal. + +.. NOTE:: + + This method is designed to find equations for D-finite objects. It may + exhibit strange behaviour for objects which are holonomic but not + D-finite. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: from ore_algebra.guessing import guess_mult + sage: data = [[binomial(n,k) for n in range(10)] for k in range(10)] + sage: guess_mult(data, OreAlgebra(ZZ['n','k'], 'Sn', 'Sk'), order=1, degree=0) + Left Ideal (Sn*Sk - Sn - 1) of Multivariate Ore algebra in Sn, Sk over Fraction Field of Multivariate Polynomial Ring in n, k over Integer Ring + sage: guess_mult(data, OreAlgebra(ZZ['x','y'], 'Dx', 'Dy'), order=1, degree=1) + Left Ideal ((x + 1)*Dx + (-y)*Dy) of Multivariate Ore algebra in Dx, Dy over Fraction Field of Multivariate Polynomial Ring in x, y over Integer Ring + sage: guess_mult(data, OreAlgebra(ZZ['n','y'], 'Sn', 'Dy'), order=1, degree=1) + Left Ideal ((-y + 1)*Sn*Dy - Sn + (-y)*Dy - 1, (-n - 1)*Sn + y*Dy - n, (-y + 1)*Sn - y) of Multivariate Ore algebra in Sn, Dy over Fraction Field of Multivariate Polynomial Ring in n, y over Integer Ring + sage: guess_mult(data, OreAlgebra(ZZ['x','k'], 'Dx', 'Sk'), order=1, degree=1) + Left Ideal (Dx*Sk + (-x - 1)*Dx - 1, x*Dx*Sk + (x + 1)*Dx + (-k)*Sk - x, (x + 1)*Dx - k, (x + 1)*Dx*Sk + (-k - 1)*Sk) of Multivariate Ore algebra in Dx, Sk over Fraction Field of Multivariate Polynomial Ring in x, k over Integer Ring +``` + + +### `guess_mult_raw` + +``` +Low-level multivariate guessing function. Do not call this method unless you know what you are doing. +In most situations, you will want to call the function `guess` instead. + +INPUT: + +- `data` -- a nested list of elements of C +- `terms` -- a list of pairs of tuples (u, v) specifying exponent vectors u, v representing terms x^u D^v +- `points` -- a list of tuples specifying indices of the data array +- `power` -- a list of functions f mapping triples (n, u, v) of nonnegative integers to elements of C +- `A` -- a list of functions mapping triples (n, u, v) to integers +- `B` -- a list of functions mapping triples (n, u, v) to integers + +OUTPUT: + +A list of vectors generating the space of all vectors in C^len(terms) for which +all(sum(prod(f[i][A[i][n[i],u[i],v[i]]]*a[B[i][n[i],u[i],v[i]]] for i in range(len(A))) +for u,v in terms) == 0 for n in points) + +SIDE EFFECT: + +Elements of the list `points` which lead to a zero equation will be discarded. +``` + +### `UnivariateOreOperatorOverUnivariateRing.polynomial_solutions` + +``` +Computes the polynomial solutions of this operator. + +INPUT: + +- ``rhs`` (optional) -- a list of base ring elements +- ``degree`` (optional) -- bound on the degree of interest. +- ``solver`` (optional) -- a callable for computing the right kernel + of a matrix over the base ring's base ring. + +OUTPUT: + +A list of tuples `(p, c_0,...,c_r)` such that `self(p) == c_0*rhs[0] + ... + c_r*rhs[r]`, +where `p` is a polynomial and `c_0,...,c_r` are constants. + +.. NOTE:: + + - Even if no ``rhs`` is given, the output will be a list of tuples ``[(p1,), (p2,),...]`` + and not just a list of plain polynomials. + - If no ``degree`` is given, a basis of all the polynomial solutions is returned. + This feature may not be implemented for all algebras. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['n']; A. = OreAlgebra(R, 'Sn') + sage: L = 2*Sn^2 + 3*(n-7)*Sn + 4 + sage: L.polynomial_solutions((n^2+4*n-8, 4*n^2-5*n+3)) + [(-70*n + 231, 242, -113)] + sage: L(-70*n + 231) + -210*n^2 + 1533*n - 2275 + sage: 242*(n^2+4*n-8) - 113*(4*n^2-5*n+3) + -210*n^2 + 1533*n - 2275 + + sage: R. = ZZ['x']; A. = OreAlgebra(R, 'Dx') + sage: L = (x*Dx - 19).lclm( x*Dx - 4 ) + sage: L.polynomial_solutions() + [(x^4,), (x^19,)] +``` + + +### `UnivariateOreOperatorOverUnivariateRing.rational_solutions` + +``` +Computes the rational solutions of this operator. + +INPUT: + +- ``rhs`` (optional) -- a list of base ring elements +- ``denominator`` (optional) -- bound on the degree of interest. +- ``degree`` (optional) -- bound on the degree of interest. +- ``solver`` (optional) -- a callable for computing the right kernel + of a matrix over the base ring's base ring. + +OUTPUT: + +A list of tuples `(r, c_0,...,c_r)` such that `self(r) == c_0*rhs[0] + ... + c_r*rhs[r]`, +where `r` is a rational function and `c_0,...,c_r` are constants. + +.. NOTE:: + + - Even if no ``rhs`` is given, the output will be a list of tuples ``[(p1,), (p2,),...]`` + and not just a list of plain rational functions. + - If no ``denominator`` is given, a basis of all the rational solutions is returned. + This feature may not be implemented for all algebras. + - If no ``degree`` is given, a basis of all the polynomial solutions is returned. + This feature may not be implemented for all algebras. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x']; A. = OreAlgebra(R, 'Dx') + sage: L = ((x+3)*Dx + 2).lclm(x*Dx + 3).symmetric_product((x+4)*Dx-2) + sage: L.rational_solutions() + [((-x^2 - 8*x - 16)/x^3,), + ((-x^5 + 96*x^3 + 584*x^2 + 1344*x + 1152)/(x^5 + 6*x^4 + 9*x^3),)] + sage: L.rational_solutions((1, x)) + [((x^2 + 8*x + 16)/(x^2 + 6*x + 9), 0, 0), + ((x^5 + 7*x^4 + 2*x^3 - 73*x^2 - 168*x - 144)/(x^5 + 6*x^4 + 9*x^3), 0, 0), + ((-2*x - 7)/(x^2 + 6*x + 9), 288, 42)] + sage: L(_[0][0]) == _[0][1] + _[0][2]*x + True + + sage: (x*(x*Dx-5)).rational_solutions([1]) + [(-x^5, 0), (1/x, -6)] + + sage: R. = ZZ['n']; A. = OreAlgebra(R, 'Sn'); + sage: L = ((n+3)*Sn - n).lclm((2*n+5)*Sn - (2*n+1)) + sage: L.rational_solutions() + [(-1/(n^3 + 3*n^2 + 2*n),), + ((-n^3 + n^2 + 6*n + 3)/(4*n^5 + 20*n^4 + 35*n^3 + 25*n^2 + 6*n),)] + + sage: L = (2*n^2 - n - 2)*Sn^2 + (-n^2 - n - 1)*Sn + n^2 - 14 + sage: y = (-n + 1)/(n^2 + 2*n - 2) + sage: L.rational_solutions((L(y),)) + [((n - 1)/(n^2 + 2*n - 2), -1)] +``` + + +## Selected operator methods + + +### `UnivariateDifferentialOperatorOverUnivariateRing.to_S` (differential operators (D)) + +``` +Return a recurrence operator annihilating the coefficient sequence of +every power series (about the origin) annihilated by ``self``. + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_S()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + the standard shift with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: A. = OreAlgebra(R, 'Dx') + sage: R2. = ZZ['n'] + sage: A2. = OreAlgebra(R2, 'Sn') + sage: (Dx - 1).to_S(A2) + (n + 1)*Sn - 1 + sage: ((1+x)*Dx^2 + Dx).to_S(A2) + (n^2 + n)*Sn + n^2 + sage: ((x^3+x^2-x)*Dx + (x^2+1)).to_S(A2) + (-n - 1)*Sn^2 + (n + 1)*Sn + n + 1 + sage: ((x+1)*Dx^3 + Dx^2).to_S(A2) + (n^3 - n)*Sn + n^3 - 2*n^2 + n +``` + + +### `UnivariateDifferentialOperatorOverUnivariateRing.to_T` (differential operators (D)) + +``` +Rewrite ``self`` in terms of the eulerian derivation `x*d/dx`. + +If the base ring of the target algebra is not a field, the +operator returned by the method may not correspond exactly to +``self``, but only to a suitable left-multiple by a term `x^k`. + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_T()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + an euler derivation with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: R2. = ZZ['y'] + sage: A. = OreAlgebra(R, 'Dx') + sage: (Dx^4).to_T(OreAlgebra(R2, 'Ty')) + Ty^4 - 6*Ty^3 + 11*Ty^2 - 6*Ty + sage: (Dx^4).to_T('Tx').to_D(A) + x^4*Dx^4 + sage: _.to_T('Tx') + Tx^4 - 6*Tx^3 + 11*Tx^2 - 6*Tx +``` + + +### `UnivariateDifferentialOperatorOverUnivariateRing.annihilator_of_integral` (differential operators (D)) + +``` +Return an operator `L` which annihilates all the indefinite integrals `\int f` +where `f` runs through the functions annihilated by ``self``. + +The output operator is not necessarily of smallest possible order. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: A. = OreAlgebra(R, 'Dx') + sage: ((x-1)*Dx - 2*x).annihilator_of_integral() + (x - 1)*Dx^2 - 2*x*Dx + sage: _.annihilator_of_associate(Dx) + (x - 1)*Dx - 2*x +``` + + +### `UnivariateDifferentialOperatorOverUnivariateRing.annihilator_of_composition` (differential operators (D)) + +``` +Return an operator `L` which annihilates all the functions `f(a(x))` where +`f` runs through the functions annihilated by ``self``, and, optionally, +a map from the quotient by ``self`` to the quotient by `L` commuting +with the composition by `a`. + +The output operator `L` is not necessarily of smallest possible order. + +INPUT: + +- ``a`` -- either an element of the base ring of the parent of ``self``, + or an element of an algebraic extension of this ring. +- ``solver`` (optional) -- a callable object which applied to a matrix + with polynomial entries returns its kernel. +- ``with_transform`` (optional) -- if `True`, also return a + transformation map between the quotients + +OUTPUT: + +- ``L`` -- an Ore operator such that for all ``f`` annihilated by + ``self``, ``L`` annihilates ``f \circ a``. +- ``conv`` -- a function which takes as input an Ore operator ``P`` and + returns an Ore operator ``Q`` such that for all functions ``f`` + annihilated by ``self``, ``P(f)(a(x)) = Q(f \circ a)(x)``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: K. = R.fraction_field()['y'] + sage: K. = R.fraction_field().extension(y^3 - x^2*(x+1)) + sage: A. = OreAlgebra(R, 'Dx') + sage: (x*Dx-1).annihilator_of_composition(y) # ann for x^(2/3)*(x+1)^(1/3) + (3*x^2 + 3*x)*Dx - 3*x - 2 + sage: (x*Dx-1).annihilator_of_composition(y + 2*x) # ann for 2*x + x^(2/3)*(x+1)^(1/3) + (3*x^3 + 3*x^2)*Dx^2 - 2*x*Dx + 2 + sage: (Dx - 1).annihilator_of_composition(y) # ann for exp(x^(2/3)*(x+1)^(1/3)) + (-243*x^6 - 810*x^5 - 999*x^4 - 540*x^3 - 108*x^2)*Dx^3 + (-162*x^3 - 270*x^2 - 108*x)*Dx^2 + (162*x^2 + 180*x + 12)*Dx + 243*x^6 + 810*x^5 + 1080*x^4 + 720*x^3 + 240*x^2 + 32*x + +If composing with a rational function, one can also compute the +transformation map between the quotients.:: + + sage: L = x*Dx^2 + 1 + sage: LL, conv = L.annihilator_of_composition(x+1, with_transform=True) + sage: print(LL) + (x + 1)*Dx^2 + 1 + sage: print(conv(Dx)) + Dx + sage: print(conv(x*Dx)) + (x + 1)*Dx + sage: print(conv(L)) + 0 + sage: LL, conv = L.annihilator_of_composition(1/x, with_transform=True) + sage: print(LL) + -x^3*Dx^2 - 2*x^2*Dx - 1 + sage: print(conv(Dx)) + -x^2*Dx + sage: print(conv(x*Dx)) + -x*Dx + sage: print(conv(conv(x*Dx))) # identity since 1/1/x = x + x*Dx + sage: LL, conv = L.annihilator_of_composition(1+x^2, with_transform=True) + sage: print(LL) + (-x^3 - x)*Dx^2 + (x^2 + 1)*Dx - 4*x^3 + sage: print(conv(Dx)) + 1/(2*x)*Dx + sage: print(conv(x*Dx)) + ((x^2 + 1)/(2*x))*Dx +``` + + +### `UnivariateDifferentialOperatorOverUnivariateRing.power_series_solutions` (differential operators (D)) + +``` +Compute the first few terms of the power series solutions of this operator. + +The method raises an error if Sage does not know how to factor +univariate polynomials over the base ring's base ring. + +The base ring has to have characteristic zero. + +INPUT: + +- ``n`` -- minimum number of terms to be computed + +OUTPUT: + +A list of power series of the form `x^\alpha + ...` with pairwise distinct +exponents `\alpha` and coefficients in the base ring's base ring's fraction field. +All expansions are computed up to order `k` where `k` is obtained by adding the +maximal `\alpha` to the maximum of `n` and the order of ``self``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: A. = OreAlgebra(R, 'Dx') + sage: ((1-x)*Dx - 1).power_series_solutions(10) # geometric series + [1 + x + x^2 + x^3 + x^4 + x^5 + x^6 + x^7 + x^8 + O(x^9)] + sage: (Dx - 1).power_series_solutions(5) # exp(x) + [1 + x + 1/2*x^2 + 1/6*x^3 + O(x^4)] + sage: (Dx^2 - Dx + x).power_series_solutions(5) # a 2nd order equation + [x + 1/2*x^2 + 1/6*x^3 - 1/24*x^4 + O(x^5), 1 - 1/6*x^3 - 1/24*x^4 + O(x^5)] + sage: (2*x*Dx - 1).power_series_solutions(5) # sqrt(x) is not a power series + [] +``` + + +### `UnivariateDifferentialOperatorOverUnivariateRing.generalized_series_solutions` (differential operators (D)) + +``` +Return the generalized series solutions of this operator. + +These are solutions of the form + + `\exp(\int_0^x \frac{p(t^{-1/s})}t dt)*q(x^{1/s},\log(x))` + +where + +* `s` is a positive integer (the object's "ramification") +* `p` is in `K[x]` (the object's "exponential part") +* `q` is in `K[[x]][y]` with `x\nmid q` unless `q` is zero (the object's "tail") +* `K` is some algebraic extension of the base ring's base ring. + +An operator of order `r` has exactly `r` linearly independent solutions of this form. +This method computes them all, unless the flags specified in the arguments rule out some +of them. + +At present, the method only works for operators where the base ring's base ring is either +QQ or a number field (i.e., no finite fields, no formal parameters). + +INPUT: + +- ``n`` (default: 5) -- minimum number of terms in the series expansions to be computed + in addition to those needed to separate all solutions from each other. +- ``base_extend`` (default: ``True``) -- whether or not the coefficients of the solutions may + belong to an algebraic extension of the base ring's base ring. +- ``ramification`` (default: ``True``) -- whether or not the exponential parts of the solutions + may involve fractional exponents. +- ``exp`` (default: ``True``) -- set this to ``False`` if you only want solutions that have no + exponential part (viz `\deg(p)\leq0`). If set to a positive rational number `\alpha`, + the method returns all those solutions whose exponential part involves only terms `x^{-i/r}` + with `i/r<\alpha`. + +OUTPUT: + +- a list of ``ContinuousGeneralizedSeries`` objects forming a fundamental system for this operator. + +.. NOTE:: + + - Different solutions may require different algebraic extensions. Thus in the list returned + by this method, the coefficient fields of different series typically do not coincide. + - If a solution involves an algebraic extension of the coefficient field, then all its + conjugates are solutions, too. But only one representative is listed in the output. + +ALGORITHM: + +- Ince, Ordinary Differential Equations, Chapters 16 and 17 +- Kauers/Paule, The Concrete Tetrahedron, Section 7.3 + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = QQ['x']; A. = OreAlgebra(R, 'Dx') + sage: L = (6+6*x-3*x^2) - (10*x-3*x^2-3*x^3)*Dx + (4*x^2-6*x^3+2*x^4)*Dx^2 + sage: L.generalized_series_solutions() + [x^3*(1 + 3/2*x + 7/4*x^2 + 15/8*x^3 + 31/16*x^4 + O(x^5)), x^(1/2)*(1 + 3/2*x + 7/4*x^2 + 15/8*x^3 + 31/16*x^4 + O(x^5))] + sage: list(map(L, _)) + [0, 0] + + sage: L = (1-24*x+96*x^2) + (15*x-117*x^2+306*x^3)*Dx + (9*x^2-54*x^3)*Dx^2 + sage: L.generalized_series_solutions(3) + [x^(-1/3)*(1 + x + 8/3*x^2 + O(x^3)), x^(-1/3)*((1 + x + 8/3*x^2 + O(x^3))*log(x) + x - 59/12*x^2 + O(x^3))] + sage: list(map(L, _)) + [0, 0] + + sage: L = 216*(1+x+x^3) + x^3*(36-48*x^2+41*x^4)*Dx - x^7*(6+6*x-x^2+4*x^3)*Dx^2 + sage: L.generalized_series_solutions(3) + [exp(3*x^(-2))*x^(-2)*(1 + 91/12*x^2 + O(x^3)), exp(-2*x^(-3) + x^(-1))*x^2*(1 + 41/3*x + 2849/36*x^2 + O(x^3))] + sage: list(map(L, _)) + [0, 0] + + sage: L = 9 - 49*x - 2*x^2 + 6*x^2*(7 + 5*x)*Dx + 36*(-1 + x)*x^3*Dx^2 + sage: L.generalized_series_solutions() + [exp(x^(-1/2))*x^(4/3)*(1 + x^(2/2) + x^(4/2)), exp(-x^(-1/2))*x^(4/3)*(1 + x^(2/2) + x^(4/2))] + sage: L.generalized_series_solutions(ramification=False) + [] + + sage: L = 2*x^3*Dx^2 + 3*x^2*Dx-1 + sage: L.generalized_series_solutions() + [exp(a_0*x^(-1/2))] + sage: _[0].base_ring() + Number Field in a_0 with defining polynomial x^2 - 2 +``` + + +### `UnivariateDifferentialOperatorOverUnivariateRing.numerical_solution` (differential operators (D)) + +``` +Evaluate an analytic solution of this operator at a point of its Riemann +surface. + +INPUT: + +- ``ini`` (iterable) - initial values, in number equal to the order `r` + of the operator +- ``path`` - a path on the complex plane, specified as a list of + vertices `z_0, \dots, z_n` +- ``eps`` (floating-point number or ball, default 1e-16) - approximate + target accuracy +- ``post_transform`` (default: identity) - differential operator to be + applied to the solutions, see examples below +- see :class:`ore_algebra.analytic.context.Context` for advanced + options + +OUTPUT: + +A real or complex ball *enclosing* the value at `z_n` of the solution `y` +defined in the neighborhood of `z_0` by the initial values ``ini`` and +extended by analytic continuation along ``path``. + +When `z_0` is an ordinary point, the initial values are defined as the +first `r` coefficients of the power series expansion at `z_0` of the +desired solution `f`. In other words, ``ini`` must be equal to + +.. math:: [f(z_0), f'(z_0), f''(z_0)/2, \dots, f^{(r-1)}(z_0)/(r-1)!]. + +Generalized initial conditions at regular singular points are also +supported. If `z_0` is a regular point, the entries of ``ini`` are +interpreted as the coefficients of the monomials `(z-z_0)^n +\log(z-z_0)^k/k!` returned by :meth:`local_basis_monomials` in the +logarithmic series expansion of `f` at `z_0`. This definition reduces +to the previous one when `z_0` is an ordinary point. + +The accuracy parameter ``eps`` is used as an indication of the +*absolute* error the code should aim for. The diameter of the result +will typically be of the order of magnitude of ``eps``, but this is not +guaranteed to be the case. (It is a bug, however, if the returned ball +does not contain the exact result.) + +See :mod:`ore_algebra.analytic` for more information, and +:mod:`ore_algebra.examples` for additional examples. + +.. SEEALSO:: :meth:`numerical_transition_matrix` + +EXAMPLES: + +First a very simple example:: + + sage: from ore_algebra import DifferentialOperators + sage: Dops, x, Dx = DifferentialOperators() + sage: (Dx - 1).numerical_solution(ini=[1], path=[0, 1], eps=1e-50) + [2.7182818284590452353602874713526624977572470936999...] + +Evaluation points can be complex and can depend on symbolic constants:: + + sage: (Dx - 1).numerical_solution([1], [0, i + pi]) + [12.5029695888765...] + [19.4722214188416...]*I + +They can even be real or complex balls. In this case, the result +contains the image of the ball:: + + sage: (Dx - 1).numerical_solution([1], [0, CBF(1+i).add_error(0.01)]) + [1.5 +/- 0.0693] + [2.3 +/- 0.0506]*I + +Here, we use a more complicated analytic continuation path in order to +evaluate the branch of the complex arctangent function obtained by +turning around its singularity at `i` once:: + + sage: dop = (x^2 + 1)*Dx^2 + 2*x*Dx + sage: dop.numerical_solution([0, 1], [0, i+1, 2*i, i-1, 0]) + [3.14159265358979...] + [+/- ...]*I + +In some cases, this method is also able to compute limits of solutions +at regular singular points. This only works when all solutions of the +differential equation tend to finite values at the evaluation point:: + + sage: dop = (x - 1)^2*Dx^3 + Dx + 1 + sage: dop.local_basis_monomials(1) + [1, + (x - 1)^(1.500000000000000? - 0.866025403784439?*I), + (x - 1)^(1.500000000000000? + 0.866025403784439?*I)] + sage: dop.numerical_solution(ini=[1, 0, 0], path=[0, 1]) + [0.6898729110219401...] + [+/- ...]*I + + sage: dop = -(x+1)*(x-1)^3*Dx^2 + (x+3)*(x-1)^2*Dx - (x+3)*(x-1) + sage: dop.local_basis_monomials(1) + [x - 1, (x - 1)^2] + sage: dop.numerical_solution([1,0], [0,1]) + 0 + + sage: (Dx*x*Dx).numerical_solution(ini=[1,0],path=[1,0]) + Traceback (most recent call last): + ... + ValueError: solution may not have a finite limit at evaluation + point 0 (try using numerical_transition_matrix()) + +To obtain the values of the solution at several points in a single run, +enclose the corresponding points of the path in length-one lists. The +output then changes to a list of (point, solution value) pairs:: + + sage: (Dx - 1).numerical_solution([1], [[i/3] for i in range(4)]) + [(0, 1.00...), (1/3, [1.39...]), (2/3, [1.94...]), (1, [2.71...])] + + sage: (Dx - 1).numerical_solution([1], [0, [1]]) + [(1, [2.71828182845904...])] + +The ``post_transform`` parameter can be used to compute derivatives or +linear combinations of derivatives of the solution. Here, we use this +feature to evaluate the tenth derivative of the Airy `Ai` function:: + + sage: ini = [1/(3^(2/3)*gamma(2/3)), -1/(3^(1/3)*gamma(1/3))] + sage: (Dx^2-x).numerical_solution(ini, [0,2], post_transform=Dx^10) + [2.34553207877...] + sage: airy_ai(10, 2.) + 2.345532078777... + +A similar, slightly more complicated example:: + + sage: (Dx^2 - x).numerical_solution(ini, [0, 2], + ....: post_transform=1/x + x*Dx) + [-0.08871870365567...] + sage: t = SR.var('t') + sage: (airy_ai(t)/t + t*airy_ai_prime(t))(t=2.) + -0.08871870365567... + +Some no +... [truncated] +``` + + +### `UnivariateDifferentialOperatorOverUnivariateRing.numerical_transition_matrix` (differential operators (D)) + +``` +Compute a transition matrix along a path drawn in the complex plane. + +INPUT: + +- ``path`` - a path on the complex plane, specified as a list of + vertices `z_0, \dots, z_n` +- ``eps`` (floating-point number or ball) - target accuracy +- see :class:`ore_algebra.analytic.context.Context` for advanced + options + +OUTPUT: + +When ``self`` is an operator of order `r`, this method returns an `r×r` +matrix of real or complex balls. The returned matrix maps a vector of +“initial values at `z_0`” (i.e., the coefficients of the decomposition +of a solution in a certain canonical local basis at `z_0`) to “initial +values at `z_n`” that define the same solution, extended by analytic +continuation along the path ``path``. + +The “initial values” are the coefficients of the monomials returned by +:meth:`local_basis_monomials` in the local logarithmic power series +expansions of the solution at the corresponding point. When `z_i` is an +ordinary point, the corresponding vector of initial values is simply + +.. math:: [f(z_i), f'(z_i), f''(z_i)/2, \dots, f^{(r-1)}(z_i)/(r-1)!]. + +The accuracy parameter ``eps`` is used as an indication of the +*absolute* error that the code should aim for. The diameter of each +entry of the result will typically be of the order of magnitude of +``eps``, but this is not guaranteed to be the case. (It is a bug, +however, if the returned ball does not contain the exact result.) + +See :mod:`ore_algebra.analytic` for more information, and +:mod:`ore_algebra.examples` for additional examples. + +.. SEEALSO:: :meth:`numerical_solution` + +EXAMPLES: + +We can compute `\exp(1)` as the only entry of the transition matrix from +`0` to `1` for the differential equation `y' = y`:: + + sage: from ore_algebra import DifferentialOperators + sage: Dops, x, Dx = DifferentialOperators() + sage: (Dx - 1).numerical_transition_matrix([0, 1]) + [[2.7182818284590452 +/- 3.54e-17]] + +Now consider a second-order operator that annihilates `\arctan(x)` and the +constants. A basis of solutions is formed of the constant `1`, of the +form `1 + O(x^2)` as `x \to 0`, and the arctangent function, of the form +`x + O(x^2)`. Accordingly, the entries of the transition matrix from the +origin to `1 + i` are the values of these two functions and their first +derivatives:: + + sage: dop = (x^2 + 1)*Dx^2 + 2*x*Dx + sage: dop.numerical_transition_matrix([0, 1+i], 1e-10) + [ [1.00...] + [+/- ...]*I [1.017221967...] + [0.4023594781...]*I] + [ [+/- ...] + [+/- ...]*I [0.200000000...] + [-0.400000000...]*I] + +By making loops around singular points, we can compute local monodromy +matrices:: + + sage: dop.numerical_transition_matrix([0, i + 1, 2*i, i - 1, 0]) + [ [1.00...] + [+/- ...]*I [3.141592653589793...] + [+/-...]*I] + [ [+/- ...] + [+/- ...]*I [1.000000000000000...] + [+/-...]*I] + +Then we compute a connection matrix to the singularity itself:: + + sage: dop.numerical_transition_matrix([0, i], 1e-10) + [ ... [+/-...] + [-0.50000000...]*I] + [ ...1.000000... [0.7853981634...] + [0.346573590...]*I] + +Note that a path that crosses the branch cut of the complex logarithm +yields a different result:: + + sage: dop.numerical_transition_matrix([0, i - 1, i], 1e-10) + [ [+/-...] + [+/-...]*I [+/-...] + [-0.5000000000...]*I] + [ [1.00000...] + [+/-...]*I [-2.356194490...] + [0.3465735902...]*I] + +In general, if the operator has rational coefficients, its singular +points are algebraic numbers. In connection problems such as the above, +they need to be specified exactly. Here is a way to do it:: + + sage: dop = (x^2 - 2)*Dx^2 + x + 1 + sage: dop.numerical_transition_matrix([0, 1, QQbar(sqrt(2))], 1e-10) + [ [2.49388146...] + [+/-...]*I [2.40894178...] + [+/-...]*I] + [[-0.203541775...] + [6.68738570...]*I [0.204372067...] + [6.45961849...]*I] + +The operator itself may be defined over a number field (with a complex +embedding):: + + sage: K. = CyclotomicField(7) + sage: (Dx - zeta7).numerical_transition_matrix([0, 1]) + [[1.32375209616333...] + [1.31434281345999...]*I] + +Some notable examples of incorrect input:: + + sage: (Dx - 1).numerical_transition_matrix([]) + Traceback (most recent call last): + ... + ValueError: empty path + + sage: ((x - 1)*Dx + 1).numerical_transition_matrix([0, 2]) + Traceback (most recent call last): + ... + ValueError: Step 0 --> 2 passes through or too close to singular + point 1 (to compute the connection to a singular point, make it a + vertex of the path) + + sage: Dops.zero().numerical_transition_matrix([0, 1]) + Traceback (most recent call last): + ... + ValueError: operator must be nonzero +``` + + +### `UnivariateEulerDifferentialOperatorOverUnivariateRing.to_D` (differential operators (D)) + +``` +Return the differential operator corresponding to ``self`` + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_D()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + the standard derivation with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: A. = OreAlgebra(R, 'Tx') + sage: (Tx^4).to_D(OreAlgebra(R, 'Dx')) + x^4*Dx^4 + 6*x^3*Dx^3 + 7*x^2*Dx^2 + x*Dx + sage: (Tx^4).to_D('Dx').to_T(A) + Tx^4 +``` + + +### `UnivariateEulerDifferentialOperatorOverUnivariateRing.to_S` (differential operators (D)) + +``` +Return a recurrence operator annihilating the coefficient sequence of +every power series (at the origin) annihilated by ``self``. + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_S()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + the standard shift with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: A. = OreAlgebra(R, 'Tx') + sage: R2. = ZZ['n'] + sage: A2. = OreAlgebra(R2, 'Sn') + sage: (Tx - 1).to_S(A2) + n - 1 + sage: ((1+x)*Tx^2 + Tx).to_S(A2) + (n^2 + 3*n + 2)*Sn + n^2 + sage: ((x^3+x^2-x)*Tx + (x^2+1)).to_S(A2) + Sn^3 + (-n - 2)*Sn^2 + (n + 2)*Sn + n +``` + + +### `UnivariateRecurrenceOperatorOverUnivariateRing.to_D` (recurrence operators (S)) + +``` +Returns a differential operator which annihilates every power series whose +coefficient sequence is annihilated by ``self``. +The output operator may not be minimal. + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_D()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + the standard derivation with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: Rn. = ZZ['n']; Rx. = ZZ['x'] + sage: A. = OreAlgebra(Rn, 'Sn') + sage: B. = OreAlgebra(Rx, 'Dx') + sage: (Sn - 1).to_D(B) + (-x + 1)*Dx - 1 + sage: ((n+1)*Sn - 1).to_D(B) + x*Dx^2 + (-x + 1)*Dx - 1 + sage: (x*Dx-1).to_S(A).to_D(B) + x*Dx - 1 +``` + + +### `UnivariateRecurrenceOperatorOverUnivariateRing.to_T` (recurrence operators (S)) + +``` +Returns a differential operator, expressed in terms of the Euler derivation, +which annihilates every power series (about the origin) whose coefficient +sequence is annihilated by ``self``. +The output operator may not be minimal. + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_T()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + the Euler derivation with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: Rn. = ZZ['n']; Rx. = ZZ['x'] + sage: A. = OreAlgebra(Rn, 'Sn') + sage: B. = OreAlgebra(Rx, 'Tx') + sage: (Sn - 1).to_T(B) + (-x + 1)*Tx - x + sage: ((n+1)*Sn - 1).to_T(B) + Tx^2 - x*Tx - x + sage: (x*Tx-1).to_S(A).to_T(B) + x*Tx^2 + (x - 1)*Tx +``` + + +### `UnivariateRecurrenceOperatorOverUnivariateRing.to_list` (recurrence operators (S)) + +``` +Computes the terms of some sequence annihilated by ``self``. + +INPUT: + +- ``init`` -- a vector (or list or tuple) of initial values. + The components must be elements of ``self.base_ring().base_ring().fraction_field()``. + If the length is more than ``self.order()``, we do not check whether the given + terms are consistent with ``self``. +- ``n`` -- desired number of terms. +- ``start`` (optional) -- index of the sequence term which is represented + by the first entry of ``init``. Defaults to zero. +- ``append`` (optional) -- if ``True``, the computed terms are appended + to ``init`` list. Otherwise (default), a new list is created. +- ``padd`` (optional) -- if ``True``, the vector of initial values is implicitly + prolonged to the left (!) by zeros if it is too short. Otherwise (default), + the method raises a ``ValueError`` if ``init`` is too short. + +OUTPUT: + +A list of ``n`` terms whose `k` th component carries the sequence term with +index ``start+k``. +Terms whose calculation causes an error are represented by ``None``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R = ZZ['x']['n']; x = R('x'); n = R('n') + sage: A. = OreAlgebra(R, 'Sn') + sage: L = ((n+2)*Sn^2 - x*(2*n+3)*Sn + (n+1)) + sage: L.to_list([1, x], 5) + [1, x, (3*x^2 - 1)/2, (5*x^3 - 3*x)/2, (35*x^4 - 30*x^2 + 3)/8] + sage: polys = L.to_list([1], 5, padd=True) + sage: polys + [1, x, (3*x^2 - 1)/2, (5*x^3 - 3*x)/2, (35*x^4 - 30*x^2 + 3)/8] + sage: L.to_list([polys[3], polys[4]], 8, start=3) + [(5*x^3 - 3*x)/2, + (35*x^4 - 30*x^2 + 3)/8, + (63*x^5 - 70*x^3 + 15*x)/8, + (231*x^6 - 315*x^4 + 105*x^2 - 5)/16, + (429*x^7 - 693*x^5 + 315*x^3 - 35*x)/16, + (6435*x^8 - 12012*x^6 + 6930*x^4 - 1260*x^2 + 35)/128, + (12155*x^9 - 25740*x^7 + 18018*x^5 - 4620*x^3 + 315*x)/128, + (46189*x^10 - 109395*x^8 + 90090*x^6 - 30030*x^4 + 3465*x^2 - 63)/256] + sage: ((n-5)*Sn - 1).to_list([1], 10) + [1, 1/-5, 1/20, 1/-60, 1/120, -1/120, None, None, None, None] +``` + + +### `UnivariateRecurrenceOperatorOverUnivariateRing.forward_matrix_bsplit` (recurrence operators (S)) + +``` +Uses division-free binary splitting to compute a product of ``n`` +consecutive companion matrices of ``self``. + +If ``self`` annihilates some sequence `c` of order `r`, this +allows rapidly computing `c_n, \ldots, c_{n+r-1}` (or just `c_n`) +without generating all the intermediate values. + +INPUT: + +- ``n`` -- desired number of terms to move forward +- ``start`` (optional) -- starting index. Defaults to zero. + +OUTPUT: + +A pair `(M, Q)` where `M` is an `r` by `r` matrix and `Q` +is a scalar, such that `M / Q` is the product of the companion +matrix at `n` consecutive indices. + +We have `Q [c_{s+n}, \ldots, c_{s+r-1+n}]^T = M [c_s, c_{s+1}, \ldots, c_{s+r-1}]^T`, +where `s` is the initial position given by ``start``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R = ZZ + sage: Rx. = R[] + sage: Rxk. = Rx[] + sage: Rxks = OreAlgebra(Rxk, 'Sk') + sage: ann = Rxks([1+k, -3*x - 2*k*x, 2+k]) + sage: initial = Matrix([[1], [x]]) + sage: M, Q = ann.forward_matrix_bsplit(5) + sage: (M * initial).change_ring(QQ['x']) / Q + [ 63/8*x^5 - 35/4*x^3 + 15/8*x] + [231/16*x^6 - 315/16*x^4 + 105/16*x^2 - 5/16] + + sage: Matrix([[legendre_P(5, x)], [legendre_P(6, x)]]) + [ 63/8*x^5 - 35/4*x^3 + 15/8*x] + [231/16*x^6 - 315/16*x^4 + 105/16*x^2 - 5/16] + + + sage: Sk = Rxks.gen() + sage: (Sk^2 - 1).forward_matrix_param_rectangular(1, 10) + ( + [1 0] + [0 1], 1 + ) + +TODO: this should detect if the base coefficient ring is QQ (etc.) +and then switch to ZZ (etc.) internally. +``` + + +### `UnivariateRecurrenceOperatorOverUnivariateRing.annihilator_of_sum` (recurrence operators (S)) + +``` +Returns an operator `L` which annihilates all the indefinite sums `\sum_{k=0}^n a_k` +where `a_n` runs through the sequences annihilated by ``self``. +The output operator is not necessarily of smallest possible order. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: A. = OreAlgebra(R, 'Sx') + sage: ((x+1)*Sx - x).annihilator_of_sum() # constructs L such that L(H_n) == 0 + (x + 2)*Sx^2 + (-2*x - 3)*Sx + x + 1 +``` + + +### `UnivariateRecurrenceOperatorOverUnivariateRing.annihilator_of_composition` (recurrence operators (S)) + +``` +Returns an operator `L` which annihilates all the sequences `f(floor(a(n)))` +where `f` runs through the functions annihilated by ``self``. +The output operator is not necessarily of smallest possible order. + +INPUT: + +- ``a`` -- a polynomial `u*x+v` where `x` is the generator of the base ring, + `u` and `v` are integers or rational numbers. If they are rational, + the base ring of the parent of ``self`` must contain ``QQ``. +- ``solver`` (optional) -- a callable object which applied to a matrix + with polynomial entries returns its kernel. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = QQ['x'] + sage: A. = OreAlgebra(R, 'Sx') + sage: ((2+x)*Sx^2-(2*x+3)*Sx+(x+1)).annihilator_of_composition(2*x+5) + (16*x^3 + 188*x^2 + 730*x + 936)*Sx^2 + (-32*x^3 - 360*x^2 - 1340*x - 1650)*Sx + 16*x^3 + 172*x^2 + 610*x + 714 + sage: ((2+x)*Sx^2-(2*x+3)*Sx+(x+1)).annihilator_of_composition(1/2*x) + (x^2 + 11*x + 30)*Sx^6 + (-3*x^2 - 25*x - 54)*Sx^4 + (3*x^2 + 17*x + 26)*Sx^2 - x^2 - 3*x - 2 + sage: ((2+x)*Sx^2-(2*x+3)*Sx+(x+1)).annihilator_of_composition(100-x) + (-x + 99)*Sx^2 + (2*x - 199)*Sx - x + 100 +``` + + +### `UnivariateRecurrenceOperatorOverUnivariateRing.annihilator_of_interlacing` (recurrence operators (S)) + +``` +Returns an operator `L` which annihilates any sequence which can be +obtained by interlacing sequences annihilated by ``self`` and the +operators given in the arguments. + +More precisely, if ``self`` and the operators given in the arguments are +denoted `L_1,L_2,\dots,L_m`, and if `f_1(n),\dots,f_m(n)` are some +sequences such that `L_i` annihilates `f_i(n)`, then the output operator +`L` annihilates sequence +`f_1(0),f_2(0),\dots,f_m(0),f_1(1),f_2(1),\dots,f_m(1),\dots`, the +interlacing sequence of `f_1(n),\dots,f_m(n)`. + +The output operator is not necessarily of smallest possible order. + +The ``other`` operators must be coercible to the parent of ``self``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = QQ['x'] + sage: A. = OreAlgebra(R, 'Sx') + sage: (x*Sx - (x+1)).annihilator_of_interlacing(Sx - (x+1), Sx + 1) + (x^3 + 17/2*x^2 + 5/2*x - 87/2)*Sx^9 + (-1/3*x^4 - 11/2*x^3 - 53/2*x^2 - 241/6*x + 14)*Sx^6 + (7/2*x^2 + 67/2*x + 205/2)*Sx^3 + 1/3*x^4 + 13/2*x^3 + 77/2*x^2 + 457/6*x + 45 +``` + + +### `UnivariateRecurrenceOperatorOverUnivariateRing.generalized_series_solutions` (recurrence operators (S)) + +``` +Returns the generalized series solutions of this operator. + +These are solutions of the form + + `(x/e)^{x u/v}\rho^x\exp\bigl(c_1 x^{1/m} +...+ c_{v-1} x^{1-1/m}\bigr)x^\alpha p(x^{-1/m},\log(x))` + +where + +* `e` is Euler's constant (2.71...) +* `v` is a positive integer +* `u` is an integer; the term `(x/e)^(v/u)` is called the "superexponential part" of the solution +* `\rho` is an element of an algebraic extension of the coefficient field `K` + (the algebra's base ring's base ring); the term `\rho^x` is called the "exponential part" of + the solution +* `c_1,...,c_{v-1}` are elements of `K(\rho)`; the term `\exp(...)` is called the "subexponential + part" of the solution +* `m` is a positive integer multiple of `v`, it is called the object's "ramification" +* `\alpha` is an element of some algebraic extension of `K(\rho)`; the term `n^\alpha` is called + the "polynomial part" of the solution (even if `\alpha` is not an integer) +* `p` is an element of `K(\rho)(\alpha)[[x]][y]`. It is called the "expansion part" of the solution. + +An operator of order `r` has exactly `r` linearly independent solutions of this form. +This method computes them all, unless the flags specified in the arguments rule out +some of them. + +Generalized series solutions are asymptotic expansions of sequences annihilated by the operator. + +At present, the method only works for operators where `K` is some field which supports +coercion to ``QQbar``. + +INPUT: + +- ``n`` (default: 5) -- minimum number of terms in the expansions parts to be computed. +- ``dominant_only`` (default: False) -- if set to True, only compute solution(s) with maximal + growth. +- ``real_only`` (default: False) -- if set to True, only compute solution(s) where `\rho,c_1,...,c_{v-1},\alpha` + are real. +- ``infolevel`` (default: 0) -- if set to a positive integer, the methods prints some messages + about the progress of the computation. + +OUTPUT: + +- a list of ``DiscreteGeneralizedSeries`` objects forming a fundamental system for this operator. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = QQ['n']; A. = OreAlgebra(R, 'Sn') + sage: (Sn - (n+1)).generalized_series_solutions() + [(n/e)^n*n^(1/2)*(1 + 1/12*n^(-1) + 1/288*n^(-2) - 139/51840*n^(-3) - 571/2488320*n^(-4) + O(n^(-5)))] + sage: list(map(Sn - (n+1), _)) + [0] + + sage: L = ((n+1)*Sn - n).annihilator_of_sum().symmetric_power(2) + sage: L.generalized_series_solutions() + [1 + O(n^(-5)), + (1 + O(n^(-5)))*log(n) + 1/2*n^(-1) - 1/12*n^(-2) + 1/120*n^(-4) + O(n^(-5)), + (1 + O(n^(-5)))*log(n)^2 + (n^(-1) - 1/6*n^(-2) + 1/60*n^(-4) + O(n^(-5)))*log(n) + 1/4*n^(-2) - 1/12*n^(-3) + 1/144*n^(-4) + O(n^(-5))] + sage: list(map(L, _)) + [0, 0, 0] + + sage: L = n^2*(1-2*Sn+Sn^2) + (n+1)*(1+Sn+Sn^2) + sage: L.generalized_series_solutions() # long time (1.4 s) + [exp(3.464101615137755?*I*n^(1/2))*n^(1/4)*(1 - 2.056810333988042?*I*n^(-1/2) - 1107/512*n^(-2/2) + (0.?e-19 + 1.489453749877895?*I)*n^(-3/2) + 2960239/2621440*n^(-4/2) + (0.?e-19 - 0.926161373412572?*I)*n^(-5/2) - 16615014713/46976204800*n^(-6/2) + (0.?e-20 + 0.03266142931818572?*I)*n^(-7/2) + 16652086533741/96207267430400*n^(-8/2) + (0.?e-20 - 0.1615093987591473?*I)*n^(-9/2) + O(n^(-10/2))), exp(-3.464101615137755?*I*n^(1/2))*n^(1/4)*(1 + 2.056810333988042?*I*n^(-1/2) - 1107/512*n^(-2/2) + (0.?e-19 - 1.489453749877895?*I)*n^(-3/2) + 2960239/2621440*n^(-4/2) + (0.?e-19 + 0.926161373412572?*I)*n^(-5/2) - 16615014713/46976204800*n^(-6/2) + (0.?e-20 - 0.03266142931818572?*I)*n^(-7/2) + 16652086533741/96207267430400*n^(-8/2) + (0.?e-20 + 0.1615093987591473?*I)*n^(-9/2) + O(n^(-10/2)))] + + sage: L = guess([(-3)^k*(k+1)/(2*k+4) - 2^k*k^3/(k+3) for k in range(500)], A) + sage: L.generalized_series_solutions() + [2^n*n^2*(1 - 3*n^(-1) + 9*n^(-2) - 27*n^(-3) + 81*n^(-4) + O(n^(-5))), (-3)^n*(1 - n^(-1) + 2*n^(-2) - 4*n^(-3) + 8*n^(-4) + O(n^(-5)))] + sage: L.generalized_series_solutions(dominant_only=True) + [(-3)^n*(1 - n^(-1) + 2*n^(-2) - 4*n^(-3) + 8*n^(-4) + O(n^(-5)))] + +TESTS:: + + sage: rop = (-8 -12*Sn + (n^2+5*n+6)*Sn^3) + sage: rop + (n^2 + 5*n + 6)*Sn^3 - 12*Sn - 8 + sage: rop.generalized_series_solutions(1) # long time (7 s) + [(n/e)^(-2/3*n)*2^n*exp(3*n^(1/3))*n^(-2/3)*(1 + 3/2*n^(-1/3) + 9/8*n^(-2/3) + O(n^(-3/3))), + (n/e)^(-2/3*n)*(-1.000000000000000? + 1.732050807568878?*I)^n*exp((-1.500000000000000? + 2.598076211353316?*I)*n^(1/3))*n^(-2/3)*(1 + (-0.750000000000000? - 1.299038105676658?*I)*n^(-1/3) + (-0.562500000000000? + 0.974278579257494?*I)*n^(-2/3) + O(n^(-3/3))), + (n/e)^(-2/3*n)*(-1.000000000000000? - 1.732050807568878?*I)^n*exp((-1.500000000000000? - 2.598076211353316?*I)*n^(1/3))*n^(-2/3)*(1 + (-0.750000000000000? + 1.299038105676658?*I)*n^(-1/3) + (-0.562500000000000? - 0.974278579257494?*I)*n^(-2/3) + O(n^(-3/3)))] +``` + + +### `UnivariateDifferenceOperatorOverUnivariateRing.to_S` (recurrence operators (S)) + +``` +Returns the differential operator corresponding to ``self`` + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_S()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + a standard shift with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: R. = ZZ['x'] + sage: A. = OreAlgebra(R, 'Fx') + sage: (Fx^4).to_S(OreAlgebra(R, 'Sx')) + Sx^4 - 4*Sx^3 + 6*Sx^2 - 4*Sx + 1 + sage: (Fx^4).to_S('Sx') + Sx^4 - 4*Sx^3 + 6*Sx^2 - 4*Sx + 1 +``` + + +### `UnivariateDifferenceOperatorOverUnivariateRing.to_D` (recurrence operators (S)) + +``` +Returns a differential operator which annihilates every power series (about +the origin) whose coefficient sequence is annihilated by ``self``. +The output operator may not be minimal. + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_D()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + the standard derivation with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: Rn. = ZZ['n']; Rx. = ZZ['x'] + sage: A. = OreAlgebra(Rn, 'Fn') + sage: B. = OreAlgebra(Rx, 'Dx') + sage: Fn.to_D(B) + (-x + 1)*Dx - 1 + sage: ((n+1)*Fn - 1).to_D(B) + (-x^2 + x)*Dx^2 + (-4*x + 1)*Dx - 2 + sage: (x*Dx-1).to_F(A).to_D(B) + x*Dx - 1 +``` + + +### `UnivariateDifferenceOperatorOverUnivariateRing.to_T` (recurrence operators (S)) + +``` +Returns a differential operator, expressed in terms of the Euler derivation, +which annihilates every power series (about the origin) whose coefficient +sequence is annihilated by ``self``. +The output operator may not be minimal. + +INPUT: + +- ``alg`` -- the Ore algebra in which the output should be expressed. + The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` + and ``alg.is_T()`` is not ``False``. + Instead of an algebra object, also a string can be passed as argument. + This amounts to specifying an Ore algebra over ``self.base_ring()`` with + the Euler derivation with respect to ``self.base_ring().gen()``. + +EXAMPLES:: + + sage: from ore_algebra import * + sage: Rn. = ZZ['n']; Rx. = ZZ['x'] + sage: A. = OreAlgebra(Rn, 'Fn') + sage: B. = OreAlgebra(Rx, 'Tx') + sage: Fn.to_T(B) + (-x + 1)*Tx - x + sage: ((n+1)*Fn - 1).to_T(B) + (-x + 1)*Tx^2 - 3*x*Tx - 2*x + sage: (x*Tx-1).to_F(A).to_T(B) + x*Tx^2 + (x - 1)*Tx +``` diff --git a/apn/lean/docs/plantri/LICENSE b/apn/lean/docs/plantri/LICENSE new file mode 100644 index 00000000..d6456956 --- /dev/null +++ b/apn/lean/docs/plantri/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/apn/lean/docs/plantri/plantri-guide.txt b/apn/lean/docs/plantri/plantri-guide.txt new file mode 100644 index 00000000..c21907cc --- /dev/null +++ b/apn/lean/docs/plantri/plantri-guide.txt @@ -0,0 +1,1579 @@ + + +Guide to using plantri (version 5.5) +==================================== + +Gunnar Brinkmann + University of Gent + Gunnar.Brinkmann@ugent.be + +Brendan McKay + Australian National University + brendan.mckay@anu.edu.au + +Heidi Van den Camp + + +INTRODUCTION. + + plantri is a program that generates certain types of graphs that are + embedded on the sphere. + + Exactly one member of each isomorphism class is output, using an amount + of memory almost independent of the number of graphs produced. This, + together with the exceptionally fast operation and careful validation, + makes the program suitable for processing very large numbers of graphs. + + Isomorphisms are defined with respect to the embeddings, so in some + cases outputs may be isomorphic as abstract graphs. Formal definitions + of isomorphism of embedded graphs are below. + + In this document we adopt the common distinction between a "plane graph" + (a graph embedded on the sphere without edge crossings) and a "planar + graph" (an abstract graph which has at least one such embedding). + +DEFINITIONS. + + When a graph is drawn on the sphere without edges crossing, the sphere is + thereby divided into regions called FACES. If the graph is connected, each + face is homeomorphic to a disk (which in this case just means that it has + no holes). We can cut a hole in the sphere in the middle of a face and + open the sphere into a plane, but we must remember that the outside region + is as much a face as the other regions even though it is no longer a disk. + + The combinatorial structure of a graph drawn on the sphere is represented + by the cyclic order of the edges at each vertex, where (according to the + arbitrary choice we will adopt) the order is clockwise if we look at + the sphere from the outside. + + a + 3------------4 + / \ /| + / \ b c / | + d / \ / | e FIGURE 1. + / \ / | + / \ / | + 0 --------- 2 ---- 1 + f g + + In the above example, the abstract graph is given by the edges + a={3,4}, b={2,3}, c={2,4}, d={0,3}, e={1,4}, f={0,2}, g={1,2}. + The embedding is given by listing the edges in clockwise order for + each vertex: + 0: d,f 1: e,g 2: b,c,g,f 3: a,b,d 4: a,e,c + Note that the cyclic order b,c,g,f is the same as c,g,f,b - the + starting point doesn't matter. + + To fully represent the embedded graph we need both the abstract graph + and the cyclic edge orders. In the case of a graph with no parallel + edges (more than one edge with the same endpoints), it is conventional + to give both at once by listing neighbours in clockwise order: + 0: 2,3 1: 2,4 2: 0,3,4,1 3: 0,4,2 4: 1,2,3 + Later we will describe a convention for representing even embeddings of + some graphs with parallel edges by cyclic neighbour lists. + + The MIRROR IMAGE of an embedded graph is obtained by reversing all the + cyclic orders. That corresponds to turning the sphere inside out. + The mirror image of the above graph is + + a + 4------------3 + |\ / \ + | \ c b / \ + e | \ / \ d FIGURE 2. + | \ / \ + | \ / \ + 1---- 2 ---------- 0 + g f + + In defining "isomorphism" for two embedded graphs, we have the choice of + whether or not to automatically regard a graph and its mirror image as + isomorphic. plantri knows both definitions: + + Let G and H be two connected embedded graphs with the same numbers of + vertices and the same number of edges. + + An ORIENTATION-PRESERVING (O-P) ISOMORPHISM from G to H is a bijection fv + from V(G) to V(H), and a bijection fe from E(G) to E(H), such that + (1) If e = {v1,v2} is in E(G), then fe(e) = {fv(v1),fv(v2)} and fe(e) + is in E(H). + (2) If (e1,e2,...,ek) is the set of edges incident with a vertex v of G, + in clockwise order, then (fe(e1),fe(e2),...,f(ek)) is the set of + edges incident with the vertex fv(v) of G, in clockwise order. + + An ORIENTATION-REVERSING (O-R) ISOMORPHISM from G to H is a bijection fv + from V(G) to V(H), and a bijection fe from E(G) to E(H), such that + (1) If e = {v1,v2} is in E(G), then fe(e) = {fv(v1),fv(v2)} and fe(e) + is in E(H). + (2) If (e1,e2,...,ek) is the set of edges incident with a vertex v of G, + in clockwise order, then (fe(e1),fe(e2),...,f(ek)) is the set of + edges incident with the vertex fv(v) of G, in anti-clockwise order. + + Note that the two definitions differ only in the penultimate word. + + An ISOMORPHISM from G to H is either an O-P isomorphism or an O-R + isomorphism. Isomorphism and O-P isomorphism (but not O-R isomorphism) + are equivalence relations, so we can speak of ISOMORPHISM CLASSES and + O-P ISOMORPHISM CLASSES. Similarly, the set of all isomorphisms and + the set all O-P isomorphisms (but not the set of all O-R isomorphisms) + from an embedded graph to itself form groups under composition: the + AUTOMORPHISM GROUP and the O-P AUTOMORPHISM GROUP. + + As is well known, ISOMORPHISM of two embedded graphs is the same as + abstract isomorphism in the case that the graphs are 3-connected. + However, if a graph is not 3-connected, its embeddings may or may not + be isomorphic. Figure 3 shows two non-isomorphic embeddings of the + same abstract graph. + + ---------- ---------- _____ + |\ /| |\ | + | \ / | | \ | FIGURE 3. + | \ / | | \ | + | | | | + ---------- ---------- + + Given an embedded graph G, we can form another embedded graph called its + PLANAR DUAL (or just DUAL) D. The vertices of D are the faces of G. + The edges of D are in 1-1 correspondence with the edges of G: the + two endpoints of an edge in D are the faces that are on either side of + the corresponding edge in G. Finally, the cyclic order of edges around + a vertex in D (which is a face in G) is the clockwise order of the + corresponding edges bounding the face in G. The graph in Figure 2 has + the following dual: + + ---------------------- + | d | + | ---------- | + | / a | | + | / C------ D + | / c / b | + |/ e / | FIGURE 4. + A --------- B | + |\ g | | + | ---------- | + | f | + ---------------------- + + The vertex A corresponds to the outside face of Figure 2. Note that the + faces of the dual correspond to the vertices of the original graph. In + fact, it is not hard to see that the dual of the dual of an embedded + graph is the original graph. Also note how the existence of vertices of + degree 2 in the original graph led to parallel edges in the dual. + + If all the faces of an embedded graph are triangles (i.e. bounded by 3 + edges) the embedded graph is called a TRIANGULATION. The literature + is divided over whether the outside face must be a triangle, but we will + take it that ALL faces are triangles. The dual of a triangulation is an + embedded cubic (trivalent) graph. A triangulation with n vertices has + exactly 3n-6 edges and 2n-4 faces. + + A graph (embedded or not) is k-CONNECTED if it cannot be disconnected by + removing fewer than k vertices. It is convenient to revise the definition + slightly for the complete graph K4: it is 3-connected but not 4-connected. + A standard theorem says that a triangulation is 3-connected if and only + if it has no loops or parallel edges. It is impossible for a planar + graph to be k-connected for k greater than 5. + + A graph (embedded or not) is CYCLICALLY K-CONNECTED if it is impossible + to remove k or fewer vertices so that the graph breaks into components of + which at least two have cycles. As before, K4 is defined to be cyclically + 3-connected but not cyclically 4-connected. Planar graphs can have + arbitrarily high cyclic connectivity. + + In many circumstances there are relationships between the connectivity of + an embedded graph and the cyclic connectivity of its dual. For example, + a triangulation is k-connected if and only if its dual is cyclically + k-connected. + + A SIMPLE graph is one with no parallel edges or loops. + + +INSTALLING plantri. + + The latest edition of plantri can be obtained from + http://cs.anu.edu.au/~bdm/plantri + + plantri.c is a C program written as a single file plantri.c. It should + compile immediately with most modern C compilers, as it only contains + code that is very standard (unless your compiler is VERY old). + + To compile plantri.c under Unix, you can use + cc -o plantri -O4 plantri.c + where "4" is the highest number your compiler accepts, or just + make plantri (but check makefile first). + +RUNNING plantri. + + To run plantri, you need to be able to enter command-line parameters. + All our examples will use standard Unix syntax. + + An example of a plantri run is: + plantri -d 16 + which makes the duals (because -d is present) of the 3-connected + triangulations with 16 vertices. In other words, it makes the + 3-connected cubic plane graphs with 28 vertices. + + The only compulsory parameter is the number of vertices ("16" in the + example). This can also be given as "28d" (the suffix 'd' means 'dual') + in which case it is converted by adding 4 then dividing by 2: + (28+4)/2 = 16. In the case of triangulations, this calculation yields + the number of faces, which is the number of vertices in the dual cubic + graph. + + Apart from the one compulsory parameter, there are three types of optional + parameters: + + * SWITCHES are introduced by a '-' character. If there are more than one + they can be arbitrarily concatenated or separated. They can also appear + anywhere. For example, these command lines are all equivalent: + plantri -m4u 10 + plantri -u -m4 10 + plantri 10 -um4 + plantri -u 10 -m4 + The meanings of the switches are explained in the next sections. + In the case of a switch taking a numerical value, such as -m, giving + it without a value is the same as giving value 0. That is, -m is + the same as -m0 . + + * An OUTPUT FILE can be given, if you want the graphs to be sent somewhere + other than standard output. Information other than graphs (such as + statistics) is written to the standard error stream. It is permitted + to use a lonely '-' to explicitly request graph output to standard + output. Example: + plantri 20 tri.20 --Send 20-vertex triangulations to file tri.20 + + * A RES/MOD pair can be given to select only a portion of the graphs that + would otherwise be produced. This pair comprises two integers with + '/' between, such as 13/100. The first integer can be from 0 to one + less than the second number. This example selects portion 13 from + portions 0, 1, ..., 99. In total, these 100 portions will be a + partition of all the graphs into 100 roughly equal parts. This is + provided to enable you to divide your computing task into pieces of + manageable size. + More information on RES/MOD pairs is given later. + + Parameters and switches may appear in any order with one exception: + the compulsory parameter (number of vertices) must precede any + output file or res/mod parameters. + +OUTPUT FORMATS. + + plantri can write graphs in a variety of different formats. + + PLANAR CODE is the default format. It is the preferred format if you plan + to feed the graph into a program that needs the embedding, and also + convenient if you don't need the embedding. However, it uses characters + which are not printable so it is not suitable for looking at by eye. + + ASCII CODE is a human-readable version of planar code. The vertices of + the graph are named by ASCII characters starting with 'a'. Example: + 7 bcdefg,agfdc,abd,acbfe,adf,aedbg,afb + This is a graph with 7 vertices a,b,c,d,e,f,g. The neighbours of + 'a' in clockwise order are b,c,d,e,f,g; and so on. Each graph occupies + one line of output. Ascii code is convenient if you just want to draw + a few graphs by hand. + To select ascii code use -a. + + EDGE CODE is an alternative for planar code that enables all plane graphs + to be encoded unambiguously even if there are multiple loops. + See Appendix B for the full definition. To select edge code use -E. + + DOUBLE CODE is a human-readable version of edge code, with both the + primal and dual graphs appearing on the same line. It begins with + the number of vertices, and then for each vertex a list of the + incident edges is given in clockwise order. Then there is the number + of faces and a list of the edges of each face in clockwise order. + The names of the edges are A, B, C, and so on in ascii order. + An example is + 8 AHB BLC CJD DIE EFA FIG GKH JLK 6 ABCDE AFGH EIF DJKGI KLBH LJC + which is an 8-vertex cubic graph with edges A..L, and its 6 faces. + To select double code use -T. + + GRAPH6 is a compact code for the abstract structure of a graph. + The embedding is not represented, so this is not a suitable code to + use if you want the embedding. It is also restricted to simple + graphs. graph6 is one of the formats supported by Brendan McKay's + 'nauty' package. Each graph occupies one line. + To select graph6 code use -g. + + SPARSE6 is a compact code for the abstract structure of a graph which is + optimized for sparse graphs. If you don't want the embedding and are + dealing with cubic graphs of 20 or more vertices, sparse6 is a good + choice. sparse6 is one of the formats supported by Brendan McKay's + 'nauty' package. Each graph occupies one line. + To select sparse6 code use -s. + + Each of those formats except for ascii code also has a standard header, + which may be written to the output at the beginning: + + format header written by default? + + planar code >>planar_code<< yes + edge code >>edge_code<< yes + graph6 >>graph6<< no + sparse6 >>sparse6<< no + + In each case the header is written with no end-of-line characters after + it (for portability reasons). To write a header when the default is not + to, or vice-versa, use -h. + + If you only want to count the graphs and not write them, use -u to + select no output. + + Details of these formats is given in Appendices A-C. + +MISCELLANEOUS SWITCHES. + + -d causes the dual graph to be written instead of the original graph. + Note that it is applied only at the output stage. All other switches + refer to the original graph before the dual is taken. For example, + -m4 (minimum degree at least 4) refers to the original graph and + not to the dual. + + -o Normally, one member of each isomorphism class is written. If this + switch is given, one member of each O-P isomorphism class is written. + Since graph6 and sparse6 formats don't encode the embedding anyway, + this switch is ignored for output purposes if you use -g or -s. + -o also implies -G. + + -G This switch is only of interest if you are using a plug-in (see + Appendix D). It ensures that the full automorphism group is + computed for each output graph. If you are not using a plug-in, + -G will just slow things down. + + -V Only output graphs with non-trivial group. If -o is given, the + O-P group is used. Otherwise, the full group. Implies -G. + + -v plantri will always tell you (by a message to standard error) the + number of graphs that were produced. If you specify -v, it might + tell you some additional statistical information. For example, if + you use -o, -v will cause it to also inform you of the number of + isomorphism classes as well as the number of isomorphism classes + which are O-P isomorphic to their mirror images. + +SELECTING THE GRAPH CLASS. + + In these instructions, the word 'primal' refers to the graph you will get + if you don't use -d, and 'dual' refers to the dual of that graph (which + you get instead by using -d). + + The character # refers to a non-negative integer. + + We begin with a few switches available in multiple circumstances. + + -m# Specify a lower bound on the minimum degree. In the dual graph this + means a lower bound on the minimum face size. The default is -m3. + + -c# Specify a lower bound on the connectivity. The meaning in the dual + graph will be explained in each case. The default is -c3. + (-c4 has a slightly weaker meaning with -q, see below.) + + -x When used in combination with -c#, the connectivity must be exactly #, + rather than at least #. (Some exceptions are noted below.) + + Now we can explain the graph classes which can be produced by plantri. + + -b but not -p + Select eulerian triangulations, where "eulerian" means that every + vertex has even degree. -m is not available except for the default + -m4 (the minimum degree is always 4 anyway). + + -c3 (default) 3-connected eulerian plane triangulation. + The dual is a 3-connected bipartite cubic graph. + + -c4 4-connected eulerian plane triangulation. + The dual is a cyclically 4-connected bipartite cubic graph. + + -c3x The difference between -c3 and -c4, namely those 3-connected + eulerian plane triangulations which have a triangle that is + not a face. + + -p but not -b + Select general plane simple graphs. In the 3-connected case, these + are also called convex polytopes. Note that isomorphism is defined + with reference to the embedding on a sphere, which means that outputs + may be isomorphic as abstract graphs if the connectivity is less + than 3. + + -m1 The minimum degree is at least 1. + -m2 The minimum degree is at least 2. + -m3 (default) The minimum degree is a least 3. + -m4 The minimum degree is at least 4. + -m5 The minimum degree is at least 5 (and so exactly 5). + + -c4 The connectivity is at least 4. + -c3 (default) The connectivity is at least 3. + -c2 The connectivity is at least 2. + -c1 The connectivity is at least 1. + -c2x The difference between -c2 and -c3, namely connectivity exactly 2. + -c1x The difference between -c1 and -c2, namely connectivity exactly 1. + + If the -c switch is used but not the -m switch, the minimum degree is + set to the same value. For example, -c2 is the same as -c2m2. + + If the -m switch is used but not the -c switch, 3-connectivity is + assumed. This means that -m1 and -m2 are ineffective without using + -c1 or -c2 as well. + + In addition, two limits can be imposed: + + -e Specify bounds on the number of edges (which is equal to the + number of edges in the dual). The default is no bounds. + For n vertices, the number of edges can be from ceil(3n/2) + (2n for -m4, ceil(5n/2) for -m5) to 3n-6. + There are four possible forms: + -e# number of edges exactly # + -e:# number of edges at most # + -e#: number of edges at least # + -e#:# number of edges from # to # + Only the lower bound is efficiently implemented. Generally + speaking, it is more efficient to do a range of edge counts + at once rather than one edge count at a time. + + -f# Specify an upper bound on the size of a face (in the dual: an + upper bound on the maximum degree). The default is no bound. + For n vertices, the largest face size can be from 3 to n-1. + + -bp or -pb + Select general plane simple bipartite graphs. These are a subset + of the class generated by -p alone, namely those which are bipartite. + The minimum degree is always at most 3, so all the parameters + available with -p are available except -c4, -m4, -m5 and -f3. + + The duals are a subclass of plane eulerian graphs. + For -c3, the duals are the 3-connected plane eulerian graphs. + + -P# Select triangulations of a disk. These are embedded simple graphs + with a distinguished "outer" face. The outer face can be any size + (here called the disk size) but the other faces must be triangles. + + The argument to -P is the disk size. If no argument (or 0) is given, + all disk sizes are permitted. If all disk sizes are needed, it is a + lot more efficient to do them all at once rather than one at a time. + + Except for the outer face, all vertices must have degree at least 3. + On the outer face, vertices of degree 2 may be permitted, according + to the -m parameter. Also, the only 2-cuts which may exist are + chords of the outer face: they are permitted for -c2 but not for -c3. + Since a vertex of degree 2 on the outer face implies a chord, the + combination -m2c3 is the same as -m3c3. + + The useful combinations of -c, -m and -x are listed: + + -c3m3 (default) no chords, no vertices degree 2 + -c2 chords allowed, no vertices degree 2 + -c2x chords required, no vertices degree 2 + -c2m2 chords allowed, degree 2 allowed + -c2xm2 chords required, degree 2 allowed + + We have c2P = c3m3P + c2xP and c2m2P = c3m3P + c2xm2P. + + The output graphs are labelled in such a way that v-w is an + edge and the outer face is on the left when looking from v-w, + where v is the first vertex and w is the second vertex. + For dual output, the first vertex corresponds to the outer + face. The dual graph is a graph which has every vertex of + degree 3 except possibly the first vertex. + + When interpretting the output, remember that the outer face is + distinguished and that this is taken into account in determining + isomorphisms. It means, for example, that some of the outputs with + outer face of size 3 will be isomorphic as abstract graphs even in + the 3-connected case. + + -q Select simple quadrangulations. These are simple plane graphs for + which every face has length 4. The dual graphs are plane quartic + graphs. + + -x is not implemented. + The useful combinations of -c and -m are listed: + + -c3m3 (default) 3-connected + dual: 3-connected simple quartic graphs + -c2m2 arbitrary + dual: 4-edge-connected (maybe not simple) + quartic multigraphs + -c2 minimum degree 3 + dual: 4-edge-connected simple quartic graphs + -c4 3-connected, no non-facial 4-cycles + dual: 3-connected, 6-cyclically-edge-connected + (simple) quartic graphs + + -Q Select general quadrangulations, allowing multiple edges. + No connectivity or degree restrictions are currently available. + The dual graphs are general plane quartic graphs, allowing multiple + edges and loops. + + -A Select Appolonian networks. These are simple plane triangulations + that can be formed starting with K4 then repeatedly dividing a face + into three by addition of a new vertex. They all have minimum + degree and connectivity equal to 3. + + The dual graphs are cubic plane graphs which can be made from K4 + by repeatedly replacing a vertex by a triangle. + + If -b, -q, -Q, -p, -P and -A are absent, the graphs found are triangulations + only restricted by connectivity and minimum degree. In this case, + there is the possibility of connectivity lower than 3. + + The useful combinations of -c, -m, -x and -t are: + + -c3m3 (default) 3-connected plane triangulation. + The dual is a 3-connected plane cubic graph. + Both primal and dual graphs are simple. + + -m5 3-connected plane triangulation with minimum degree 5. + The dual is a 3-connected plane cubic graph with no faces + smaller than pentagons. Both primal and dual graphs are simple. + + -c5 5-connected plane triangulation (implies minimum degree 5). + The dual is a cyclically 5-connected plane cubic graph. + Both primal and dual graphs are simple. + + -m5c4 4-connected plane triangulation with minimum degree 5. The + The dual is a cyclically 4-connected plane cubic graph with + no faces smaller than pentagons. Both primal and dual graphs + are simple. + + -m5c3x 3-connected plane triangulation with minimum degree 5 + and at least one non-facial triangle. The dual is a + 3-connected plane cubic graph with no faces smaller than + pentagons but at least one cyclic 3-cut. Both primal and + dual graphs are simple. + + -m5c4x 4-connected plane triangulation with minimum degree 5 + and at least one separating 4-cycle. The dual is a + 4-connected plane cubic graph with no faces smaller than + pentagons but at least one cyclic 4-cut. Both primal and + dual graphs are simple. + + -m4 3-connected plane triangulation with minimum degree at least 4. + The dual is a 3-connected plane cubic graph with no triangles. + Both primal and dual graphs are simple. + + -c4 4-connected plane triangulation (implies minimum degree >= 4). + The dual is a cyclically 4-connected plane cubic graph. + Both primal and dual graphs are simple. + + -c4x, -c5x are not allowed (but see -m5c4x). + + -m4c3x 3-connected plane triangulation with minimum degree at + least 4 and at least one non-facial triangle. The dual is a + 3-connected plane cubic graph with no triangles but at least + one cyclic 3-cut. Both primal and dual graphs are simple. + + -c2 2-connected plane triangulation with minimum degree at least 3. + There may be parallel edges (but remember it is a triangulation + so there must be things between each pair of them). There are + no loops. The dual is a 2-connected simple plane cubic graph. + + -c2x Same as -c2 except that there must be at least one pair of + parallel edges. In the dual, at least one cutset of size 2. + + -m2c2 2-connected plane triangulation with minimum degree at least 2. + There can be parallel edges but no loops. The dual is a + 2-connected plane cubic graph which may have multiple edges + but has no loops. + + In the case of -c1, there is an extra switch -t which changes the + class. For a triangulation a "special configuration" consists of + two faces that consist of a double edge with a loop inside at one + end and a loop outside at the other end. In the dual cubic graph, + this corresponds to a double edge which does not bound a face + (so it has an edge pointing inside at one end and an edge pointing + outside at the other end). In all cases, special configurations + are allowed if -t is used and forbidden otherwise. + + In these descriptions loops and double edges are permitted except + as indicated. + + -c1 (same as -m3c1) Planar triangulation with minimum degree at + least 3 and no special configurations. The dual is a plane + cubic graph no non-facial 2-cycles. + + -c1t (same as -m3c1t) Arbitrary plane triangulation with minimum + degree at least 3. The dual is an arbitrary plane cubic graph. + + -m2c1 Planar triangulation with minimum degree at least 2 but no + special configurations. The dual is a plane cubic graph + with no loops or non-facial 2-cycles. + + -m2c1t Planar triangulation with minimum degree at least 2. + The dual is a plane cubic graph with no loops. + + -m1c1 Planar triangulation with no special configurations. + The dual is a plane cubic graph with no non-facial 2-cycles. + + -m1c1t Arbitrary plane triangulation. The dual is an arbitrary + plane cubic graph. + + We have c2 = c2x + c3, c1 = c1x + c2, and c1t = c1tx + c2. + Also m2c1 = m2c1x + m2c2 and m1c1 = m1c1x + m1c2. + Also m2c1t = m2c1tx + m2c2 and m1c1t = m1c1tx + m1c2. + Also m4 = m4c3x + c4, m5c4 = m5c4x + c5, and m5 = m5c4x + m5c3x + c5. + +MORE ON RES/MOD SPLITTING. + + The feature selected by the optional res/mod parameter to plantri is one + of its greatest strengths. The set of objects is divided into mod disjoint + classes and only the res-th class is generated. It is necessary that + 0 <= res <= mod-1. The splitting is designed so that the overhead is at + most 5 seconds per run for a 500MHz machine. Also, for problems where + there are very many objects altogether, the value of mod can be at least + as large as 10,000 and still have reasonable uniformity of class size. + + The definition of the classes obeys the normal laws of modulo arithmetic. + For example, class 1/5 is the union of 1/10 and 6/10 (since the numbers + equal to 1 modulo 5 are the numbers equal to 1 or 6 modulo 10). This + enables classes to be further split into smaller pieces if the need arises. + + To determine the actual cost of splitting, and the maximum number of + classes available, run the program plantri_s (known to the makefile). + For example: + % plantri_s -b 30 + 9030731 splitting cases at level=24; cpu=7.63 sec + This says that splitting into up to 9030731 cases is feasible (though the + splitting won't be very uniform if you use that many) and the cost of the + splitting is about 7.6 seconds for each run. (In this case, it means that + using 400 classes incurs a splitting penalty of only one percent.) + + Plugins can change the splitting level by defining splithint in the + expansion of PLUGIN_INIT. + + The switch -X increases the splitting level by 1 if possible, making the + splitting more uniform at the cost of more overhead. You can repeat it, + as in -XX. You must use the same number of Xs for each part. + +APPENDIX A. Definition of PLANAR CODE. + + PLANAR CODE is the default output format for plantri. The vertices of + the graph are numbered starting at 1. PLANAR CODE represents the graph + by a series of bytes, whose unsigned numerical values (0..255) are + significant. The first byte gives the number of vertices n. Then there + are n sections, where section v contains the neighbours of vertex v in + clockwise order followed by a zero byte. There is no end-of-line + character appended. + + For example, the graph of Figure 1 is represented by the following + byte values: + + 5 3 4 0 3 5 0 1 4 5 2 0 1 5 3 0 2 3 4 0 + + In case there are parallel edges, there might be more than one graph + whose PLANAR CODE is the same up to rotation of the neighbour lists. + To resolve this ambiguity, plantri makes the following convention: + for each vertex v except for the first vertex, if the least numbered + vertex that has v as a neighbour is w, then the first w in the section + for v represents the same edge as the first v in the section for w. + + In case of all the graph classes generated by plantri that have no + multiple loops, and also for all classes of triangulations, it can be + proved that for every v > 1 we have w < v and the embedded graph is + uniquely reconstructible from the code. + + In addition to the encodings of graphs, a PLANAR CODE file by default + begins with the 15 characters >>planar_code<< without end-of-line + characters. + +APPENDIX B. Definition of EDGE CODE. + + EDGE CODE is an alternative to PLANAR CODE that has the advantage of + being uniquely decodable for all plane graphs (even with multiple loops). + The undirected edges are numbered 0,1,... consecutively but in + no particular order, and for each vertex a list of the incident + edge numbers in clockwise order is given. Note that a loop appears + twice in such a list, and in general each edge number appears + exactly twice altogether. + + The code consists of a header and a body. The header has one of + two forms: + 1. A single byte of value 1-255. In this case, the value of the + byte is the size of the body in bytes. All edge numbers in the + body will be encoded using L=1 bytes. + 2. The byte 0, a byte (K<<4)+L (where 1<=K,L<=15), and a bigendian + unsigned number S stored in K bytes. In this case, S is the size + of the body in bytes and L is the number of bytes used for edge + numbers in the body. The size of the header is 1+1+K bytes. + + The body has a section for each vertex. In each section, the edge + numbers for the incident edges are given in clockwise order, using + an L-byte bigendian integer for each. Each vertex section except + the last is followed by a single byte of value 255. (Note that this + implies L is large enough that the largest edge number has first + byte value at most 254.) + + In plantri, the only possibility for the second header type is K=2, L=1. + + In addition to the encodings of graphs, an EDGE CODE file by default + begins with the 13 characters >>edge_code<< without end-of-line + characters. + +APPENDIX C. Definition of GRAPH6 and SPARSE6. + + All numbers in this description are in decimal unless obviously in + binary. GRAPH6 and SPARSE6 are text formats, and a file containing + them is a text file. + + Apart from the header, there is one object per line. Apart from the + header and the end-of-line characters, all bytes have a value in the + range 63-126 (which are all printable ASCII characters). + + BIT VECTORS: + + A bit vector x of length k can be represented as follows. + Example: 1000101100011100 + + (1) Pad on the right with 0 to make the length a multiple of 6. + Example: 100010110001110000 + + (2) Split into groups of 6 bits each. + Example: 100010 110001 110000 + + (3) Add 63 to each group, considering them as bigendian binary numbers. + Example: 97 112 111 + + These values are then stored one per byte. + So, the number of bytes required is ceiling(k/6). + + Let R(x) denote this representation of x as a string of bytes. + + SMALL NONNEGATIVE INTEGERS: + + Let n be an integer in the range 0-262143 (262143 = 2^18-1). + + If 0 <= n <= 62, define N(n) to be the single byte n+63. + If n >= 63, define N(n) to be the four bytes 126 R(x), where + x is the bigendian 18-bit binary form of n. + + Examples: N(30) = 93 + N(12345) = N(000011 000000 111001) = 126 69 63 120 + + + GRAPH6 format: + + Suppose G has n vertices. Write the upper triangle of the adjacency + matrix of G as a bit vector x of length n(n-1)/2, using the ordering + (0,1),(0,2),(1,2),(0,3),(1,3),(2,3),...,(n-1,n). + + Then the graph is represented as N(n) R(x). + + Example: Suppose n=5 and G has edges 0-2, 0-4, 1-3 and 3-4. + + x = 0 10 010 1001 + + Then N(n) = 68 and R(x) = R(010010 100100) = 81 99. + So, the graph is 68 81 99. + + Note that GRAPH6 format cannot represent loops or parallel edges. + + SPARSE6 format: + + The encoded graph consists of: + (1) The character ':'. (This is present to distinguish + the code from GRAPH6 format.) + (2) The number of vertices. + (3) A list of edges. + (4) end-of-line + + Loops and multiple edges are supported, but not directed edges. + + Number of vertices n: Represented as N(n) like in GRAPH6 format. + + List of edges: + + Let k be the number of bits needed to represent n-1 in binary. + The remaining bytes encode a sequence R(z) where + z = b[0] x[0] b[1] x[1] b[2] x[2] ... b[m] x[m] ... + + Each b[i] occupies 1 bit, and each x[i] occupies k bits. + Padding at the end is chosen so that the decoding algorithm below + does not imply any spurious edges. + + The vertices of the graph are 0..n-1. + The edges encoded by this sequence are determined thus: + + v = 0 + for i from 0 to m do + if b[i] = 1 then v = v+1 endif; + if x[i] > v then v = x[i] else output {x[i],v} endif + endfor + + Example: :Fa@x^ + ':' indicates sparse6 format. + Subtract 63 from the other bytes and write them in binary, six bits each. + 000111 100010 000001 111001 011111 + The first byte is not 63, so it is n. n=7 + n-1 needs 3 bits (k=3). Write the other bits in groups of 1 and k: + 1 000 1 000 0 001 1 110 0 101 1 111 + This is the b/x sequence 1,0 1,0 0,1 1,6 0,5 1,7. + The 1,7 at the end is just padding. + The remaining pairs give the edges 0-1 1-2 5-6. + + +APPENDIX D. Writing Plug-ins for plantri. + + plantri has a facility for making certain compile-time changes to its + behaviour. This requires some amount of knowledge of how the program + works, and here we will give a little of that. A typical use for + a plug-in is to filter the output graphs before they are written. + This is a good idea if you are only wanting some subset of the graphs, + because plantri is so fast that writing graphs out and reading them + into another program takes about as long as generating them. + + Vertices in plantri are numbered starting at 0. There are global + variables nv and ne which contain the number of vertices and the + number of DIRECTED edges (which is twice the number of edges). + + In the case of disk triangulations, there are some occasions when + one vertex number is unused. In this case, the global int variable + missing_vertex indicates what is missing. If nothing is missing, + missing_vertex < 0. For example, if nv=7 and missing_vertex=2, the + vertices are actually numbered 0,1,3,4,5,6,7. + + The graph is held as a collection of directed edges (type EDGE). + These edges are structures referenced by pointers. They have these + fields, amongst others: + + int start; the vertex at the start of the edge + int end; the vertex at the end of the edge + EDGE *invers; the directed edge which is the reverse of this one + EDGE *next; the next edge in clockwise order around vertex start + EDGE *prev; the previous edge in clockwise order around vertex start + + To find the edges, there is an array firstedge[0..], type EDGE*. + The value of firstedge[i] is a pointer to one of the edges starting + at vertex v. + + For example, to "look at" all the neighbours of vertex v we can do: + + EDGE *e,*elast; + + e = elast = firstedge[v]; + do + { + look at e->end; + e = e->next; + } while (e != elast); + + Another example is the tracing of a face. Suppose we have an edge e and + we want to "look at" all the edges bounding the face on the right of e. + + elast = e; + do + { + look at e; + e = e->invers->prev; + } while (e != elast); + + Use e = e->invers->next instead if you are interested in the face on + the left of e. + + Another useful global array is degree[0..], which contains the + degrees of the vertices. Another way to "look at" all the neighbours + of vertex v is this: + + for (count = degree[v], e = firstedge[v]; --count >= 0; e = e->next) + { + look at e->end + } + + + To write a plug-in, you need to define some things in a separate source + file (let's call it plugin.c), and make the name of that source file + available when compiling plantri.c. For example, on most Unix systems: + cc -o plantri_plugin -O4 '-DPLUGIN="plugin.c"' plantri.c + All the quotes of both types are required. + + This process causes the text of plugin.c to be read into the text of + plantri.c, so everything defined in each file is available in both. + The work of the plug-in is achieved by defining macros. Here we list + the macros that might be defined, and their meanings. If you don't + want these functions, just don't define the macros. + + FILTER This is the name of a procedure that is called for each + isomorphism type of graph that would normally be output (except + that in the case of -d it is the original graph before taking + the dual). The calling sequence is like this: + int FILTER(int nbtot, int nbop, int doflip) + The procedure must return an int value. If the value 0 is + returned, the graph is not written. Otherwise it is written. + + The meanings of the parameters: + nbtot = total number of automorphisms + nbop = number of canonical labellings which are O-P. + If there are O-R automorphisms, nbop=nbtot/2, while if + there are none nbop=0 or nbop=nbtot. + doflip = 0 if there is an orientation-reversing automorphism, + otherwise 1 + + nbtot, nbop, doflip are only guaranteed correct if -G or -o is + given. In that case the full automorphism group is available; + contact the authors for details. + + Without -G and -o, doflip=0 and the other parameters are undefined. + + These rules mean that doflip+1 is the number of graphs which are + to be written (except for the embedding-insensitive formats graph6 + and sparse6, for which only one will be written). If you are using + FILTER to count outputs with a particular property, count each + graph with a weight of doflip+1. + + This procedure can be used to write the graph in another format. + The normal output file (an open text file) is outfile, except + if -u is given, in which case you will have to open a file + yourself or use stdout. + + SUMMARY This is called at the end of the computation before the final + summary statistics are produced by plantri. Type: + void SUMMARY(void) + Its main use is to write information gathered by FILTER and other + plug-in components. If you don't want the normal summary as well, + set the global variable dosummary to 0 before returning. + + Look in plantri.c to see how statistics are collected and written. + All statistics should be written to the file msgfile. + + PLUGIN_INIT This is called at the start of execution, after the + command-line switches have been decoded but before any graphs + are generated. You can use it to perform tasks such as: + (a) Test if the switches are valid for this plug-in. + (b) Set switch values to appropriate default values. + (c) Initialize data-structures used by this plug-in. + + PLUGIN_SWITCHES This can be defined to add extra switches. The mechanism + for detecting switches, and their values, can be best seen by + examining plantri.c. Here are two simple cases: + (a) Add a boolean switch -z: + #define PLUGIN_SWITCHES else if (arg[j] == 'z') zswitch = TRUE; + (b) Add a switch -z that takes an integer value: + #define PLUGIN_SWITCHES else if (arg[j] == 'z') \ + zvalue = getswitchvalue(arg,&j); + In each case you have to define and initialize the new variables. + You can do that at the top level in plugin.c: + (a) static int zswitch = FALSE; + (b) static int zvalue = -1; + Checking that zvalue is valid, or giving it a default value if it + is not specified (i.e. is still -1), can be done using PLUGIN_INIT. + + If you change the switches, you should also redefine the macro + SWITCHES that appears in the first line of plantri.c. It is + only used in error messages. + + PRE_FILTER_* These are the most difficult macros to use, as considerable + knowledge of the internals of the program is required. plantri + operates by starting with the smallest graphs in the required + class, then expanding them by a few vertices at a time until the + output size is reached. The exact method for expanding a graph + depends on the graph class. The value of PRE_FILTER_* is an + expression that is evaluated for each intermediate graph computed + during the generation process that is smaller (or less constructed + in some other sense) than the output size. If the value of the + expression is 0, that intermediate graph is not expanded (so none + of its descendants appear in the output). If the value is not 0, + expansion proceeds as normal. + + The actual macros available are + PRE_FILTER_SIMPLE, PRE_FILTER_MIN4, PRE_FILTER_BIP, + PRE_FILTER_POLY, PRE_FILTER_DOUBLE, PRE_FILTER_ORDLOOP, + PRE_FILTER_SPECIALLOOP, PRE_FILTER_QUAD, PRE_FILTER_MIN5. + + A few more complex macros are available, but describing them would + require too much detail about plantri internals. + + Some examples of plug-ins are distributed with plantri: + mdcount.c (makes plantri_mdcount) - count graphs by minimum degree + degseq.c (makes plantri_deg) - counts graphs by degree sequence + nft.c (makes plantri_nft) - counts graphs by non-facial triangles + maxdeg.c (makes plantri_md) - imposes a bound on the maximum degree + allowed_deg.c (makes plantri_ad) - specify which degrees are permitted + faceorbits.c (makes plantri_fo) - count plane embeddings with + distinguished outer face + +APPENDIX E. Graph Counts. + + In this section we list some counts of the graph classes that can be + generated using plantri. If you compute any additional numbers in + any of these classes, please send them to us for inclusion. + + The column headings in these tables are: + + nv = number of vertices (or faces in the dual) + ne = number of edges (same in the dual) + nf = number of faces (or vertices in the dual) + + all = count of isomorphism classes + O-P = count of orientation-preserving isomorphism classes. + + ---------------------------------------------------------------- + + 3-connected plane triangulations. + + nv ne nf all O-P + + 4 6 4 | 1 1 + 5 9 6 | 1 1 + 6 12 8 | 2 2 + 7 15 10 | 5 6 + 8 18 12 | 14 17 + 9 21 14 | 50 73 + 10 24 16 | 233 389 + 11 27 18 | 1249 2274 + 12 30 20 | 7595 14502 + 13 33 22 | 49566 97033 + 14 36 24 | 339722 672781 + 15 39 26 | 2406841 4792530 + 16 42 28 | 17490241 34911786 + 17 45 30 | 129664753 259106122 + 18 48 32 | 977526957 1954315346 + 19 51 34 | 7475907149 14949368524 + 20 54 36 | 57896349553 115784496932 + 21 57 38 | 453382272049 906736988527 + 22 60 40 | 3585853662949 7171613842488 + 23 63 42 | 28615703421545 57231089062625 + + ---------------------------------------------------------------- + + 3-connected plane triangulations with minimum degree at least 4, + (plantri -m4), and 4-connected plane triangulations (plantri -c4). + + m4 c4 + + nv ne nf all O-P all O-P + + 6 12 8 | 1 1 | 1 1 + 7 15 10 | 1 1 | 1 1 + 8 18 12 | 2 2 | 2 2 + 9 21 14 | 5 5 | 4 4 + 10 24 16 | 12 14 | 10 12 + 11 27 18 | 34 45 | 25 32 + 12 30 20 | 130 194 | 87 128 + 13 33 22 | 525 891 | 313 519 + 14 36 24 | 2472 4499 | 1357 2430 + 15 39 26 | 12400 23603 | 6244 11765 + 16 42 28 | 65619 127887 | 30926 59915 + 17 45 30 | 357504 705770 | 158428 311744 + 18 48 32 | 1992985 3959653 | 836749 1659633 + 19 51 34 | 11284042 22494163 | 4504607 8971845 + 20 54 36 | 64719885 129227103 | 24649284 49195863 + 21 57 38 | 375126827 749646288 | 136610879 272940855 + 22 60 40 | 2194439398 4387116659 | 765598927 1530417953 + 23 63 42 | 12941995397 25878895923 | 4332047595 8661936137 + 24 66 44 | 76890024027 153765144588 | 24724362117 49442678322 + 25 69 46 | 459873914230 919704309272 | 142205424580 284393946501 + 26 72 48 | 2767364341936 5534600480206 | 823687567019 1647327455726 + 27 75 50 | 16747182732792 | 4801749063379 + + Note: An earlier version of this table gave a different value for + the first count on the nv=23 row. That was due to a clerical error + and not to a program bug. + + ---------------------------------------------------------------- + + plane triangulations without 3-connectivity requirement. + A "special configuration" is two faces formed by a pair of parallel + edges with a loop inside one end and a loop outside the other end. + conn = a lower bound on the connectivity + delta = a lower bound on the minimum degree + + conn=2 delta=3 (plantri -c2) + conn=1 delta=3 and no special configuration (plantri -c1) + conn=1 delta=3 (plantri -c1t). + + conn=2 delta=2 (plantri -m2c2) + conn=1 delta=2 and no special configuration (plantri -m2c1) + conn=1 delta=2 (plantri -m2c1t). + + conn=1 delta=1 and no special configuration (plantri -m1c1) + conn=1 delta=1 (plantri -m1c1t). + + c2 + + nv all O-P + + 4 | 1 1 + 5 | 1 1 + 6 | 3 3 + 7 | 8 9 + 8 | 32 37 + 9 | 131 183 + 10 | 723 1156 + 11 | 4360 7713 + 12 | 29632 55436 + 13 | 213168 412193 + 14 | 1606633 3158392 + 15 | 12473723 24736138 + 16 | 99141919 197448348 + 17 | 802392930 1601481238 + 18 | 6593377305 13173471151 + 19 | 54883010885 109712447949 + 20 | 462038444588 923858502128 + 21 | 3928893849911 7856893675780 + + + c1 c1t + + nv all O-P all O-P + + 4 | 1 1 | 1 1 + 5 | 1 1 | 1 1 + 6 | 3 3 | 3 3 + 7 | 9 10 | 9 10 + 8 | 37 42 | 38 43 + 9 | 172 230 | 178 236 + 10 | 993 1523 | 1041 1577 + 11 | 6308 10737 | 6652 11188 + 12 | 44145 80319 | 46738 84194 + 13 | 327051 620134 | 347050 653271 + 14 | 2530761 4913112 | 2691419 5198809 + 15 | 20179785 39705720 | 21509955 42184083 + 16 | 164672106 326420796 | 175969274 348088277 + 17 | 1368137926 2723097802 | 1465921468 2913967487 + 18 | 11536196188 23012381739 | 12395111621 24706425434 + 19 | 98494508358 196713776094 | 106126249031 211856940558 + 20 | 850073936750 1698875856077 | 918520748281 1835160731391 + 21 | 7406965136219 14808015829668 | 8025676381104 16042357404748 + + + m2c2 + + nv all O-P + + 3 | 1 1 + 4 | 2 2 + 5 | 4 4 + 6 | 14 14 + 7 | 54 66 + 8 | 291 409 + 9 | 1873 3078 + 10 | 14468 26044 + 11 | 123730 235054 + 12 | 1139820 2223598 + 13 | 11012340 21770878 + 14 | 110159674 219136678 + 15 | 1131227001 2256904588 + 16 | 11864336461 23702178103 + 17 | 126639415621 253151362072 + 18 | 1372246820875 2743873167600 + 19 | 15065904311738 30128766834832 + + m2c1 m2c1t + + nv all O-P all O-P + + 3 | 1 1 1 1 + 4 | 2 2 2 2 + 5 | 5 5 5 5 + 6 | 19 19 20 20 + 7 | 94 112 100 118 + 8 | 581 802 634 862 + 9 | 4297 6864 4738 7451 + 10 | 36388 63985 40412 70132 + 11 | 337952 630270 376812 696162 + 12 | 3349489 6455215 3749104 7180627 + 13 | 34738800 68154023 39044043 76306202 + 14 | 372459154 737599845 420546653 830919184 + 15 | 4096051566 8151111206 4647701181 9236590422 + 16 | 45968549270 91704568206 52427373251 104510610443 + 17 | 524625804817 1047919071939 601467756683 1200901913663 + 18 | 6073627332266 12139545642813 6999845695102 13987563528656 + + m1c1 m1c1t + + nv all O-P all O-P + + 3 | 2 2 2 2 + 4 | 5 5 6 6 + 5 | 21 22 25 26 + 6 | 125 154 156 191 + 7 | 997 1502 1272 1904 + 8 | 9906 17017 12924 22078 + 9 | 115036 213553 152706 282388 + 10 | 1478952 2855841 1997650 3848001 + 11 | 20342243 40036445 27960796 54953996 + 12 | 293294847 582364274 410416310 814302292 + 13 | 4378778380 8729474470 6239790783 12434664412 + 14 | 67181358581 134172729792 97510238990 194705958478 + 15 | 1053929763051 2106555903824 1558296770458 3114359909400 + 16 | 16846298319763 25375343842763 50734620915690 + + ---------------------------------------------------------------- + + 3-connected plane Eulerian triangulations (plantri -b), + and 4-connected plane Eulerian triangulations (plantri -bc4). + + b bc4 + + nv ne nf all O-P all O-P + + 6 12 8 | 1 1 | 1 1 + 7 15 10 | 0 0 | 0 0 + 8 18 12 | 1 1 | 1 1 + 9 21 14 | 1 1 | 0 0 + 10 24 16 | 2 2 | 2 2 + 11 27 18 | 2 2 | 1 1 + 12 30 20 | 8 9 | 5 6 + 13 33 22 | 8 11 | 3 3 + 14 36 24 | 32 41 | 18 22 + 15 39 26 | 57 89 | 19 25 + 16 42 28 | 185 296 | 79 112 + 17 45 30 | 466 829 | 134 214 + 18 48 32 | 1543 2772 | 501 817 + 19 51 34 | 4583 8746 | 1147 2058 + 20 54 36 | 15374 29461 | 3976 7188 + 21 57 38 | 50116 98342 | 11055 21036 + 22 60 40 | 171168 336881 | 37231 71185 + 23 63 42 | 582603 1156559 | 114560 224103 + 24 66 44 | 2024119 4024297 | 384053 753561 + 25 69 46 | 7057472 14075250 | 1244056 2464355 + 26 72 48 | 24873248 49638364 | 4193857 8321649 + 27 75 50 | 88111772 176037177 | 13977946 27841706 + 28 78 52 | 314301078 628107157 | 47522279 94737950 + 29 81 54 | 1126716000 2252541666 | 161222224 321889797 + 30 84 56 | 4060375677 8118442511 | 553033544 1104620101 + 31 87 58 | 14697571234 29390845869 | 1899744032 3796766424 + 32 90 60 | 53432834170 106854715443 | 6571595339 13136256710 + 33 93 62 | 195015189626 390009407529 | 22793047258 45572625554 + 34 96 64 | 714404259151 1428755867040 | 79449718217 158865787212 + 35 99 66 | 2626130395699 5252157292165 | 277760027418 555452882736 + 36 102 68 | 9685071313079 | 974836112457 + + ---------------------------------------------------------------- + + Convex polytopes (3-connected plane simple graphs, plantri -p), + and convex polytopes with minimum degree at least 4 (plantri -pm4). + + p pm4 + + nv all O-P all O-P + + 4 1 1 | + 5 2 2 | + 6 7 8 | 1 1 + 7 34 45 | 1 1 + 8 257 419 | 4 4 + 9 2606 4798 | 14 16 + 10 32300 62754 | 67 99 + 11 440564 872411 | 428 720 + 12 6384634 12728018 | 3515 6531 + 13 96262938 192324654 | 31763 61677 + 14 1496225352 2991463239 | 307543 607787 + 15 23833988129 47663036427 | 3064701 6101800 + 16 387591510244 775158142233 | 31199068 62288750 + 17 6415851530241 12831576165782 | 322264655 644101914 + 18 107854282197058 | 3369911732 6738127018 + 19 | 35611596455 71216447022 + 20 | 379881408164 759735751770 + 21 | 4086847012014 8173585336482 + + ---------------------------------------------------------------- + + Triangulations of a disk: 3-connected (plantri -P), or exactly + 2-connected but without vertices of degree 2 (plantri -Pc2x), + or exactly 2-connected with vertices of degree 2 on the outer + face permitted (plantri -Pc2m2). + + P + + nv all O-P + + 4 1 1 + 5 2 2 + 6 7 8 + 7 27 37 + 8 132 213 + 9 773 1386 + 10 5017 9524 + 11 34861 68057 + 12 253676 501858 + 13 1903584 3788747 + 14 14616442 29170667 + 15 114254053 228295618 + 16 906266345 1811802818 + 17 7277665889 14552804492 + 18 59066524810 118124257451 + 19 483864411124 967698049455 + 20 3996427278475 7992746427963 + 21 33250623548406 66500865364037 + + Pc2x Pc2xm2 + + nv all O-P all O-P + + 3 | 1 1 + 4 | 1 1 + 5 | 2 2 + 6 1 1 | 9 12 + 7 4 5 | 36 56 + 8 27 42 | 196 341 + 9 163 289 | 1160 2168 + 10 1131 2130 | 7616 14732 + 11 8030 15631 | 52605 103619 + 12 59412 117319 | 379339 753336 + 13 448361 891666 | 2814161 5610649 + 14 3447550 6877352 | 21363658 42666989 + 15 26887369 53713758 | 165164873 330125084 + 16 212338376 424461698 | 1296637273 2592566706 + 17 1695218973 3389687444 | 10312933521 20623423424 + 18 13666153626 27329645755 | 82959235392 165909929181 + 19 111136594337 222263795690 | 674004472100 1347979078869 + 20 910959545329 1821885598755 | 5524400982592 11048696658907 + 21 7520705838434 15041292477945 | 45637448298918 91274524809807 + + ---------------------------------------------------------------- + + 3-connected plane triangulations with minimum degree 5 (plantri -m5), + and 3-connected plane graphs (convex polytopes) with minimum degree 5 + (plantri -pm5). + + triangulations polytopes + + nv ne nf all O-P all O-P + + 12 30 20 | 1 1 | 1 1 + 13 33 22 | 0 0 | 0 0 + 14 36 24 | 1 1 | 1 1 + 15 39 26 | 1 1 | 1 1 + 16 42 28 | 3 4 | 5 6 + 17 45 30 | 4 4 | 8 8 + 18 48 32 | 12 17 | 30 46 + 19 51 34 | 23 33 | 85 135 + 20 54 36 | 73 117 | 392 686 + 21 57 38 | 192 331 | 1587 2961 + 22 60 40 | 651 1180 | 7657 14744 + 23 63 42 | 2070 3899 | 36291 71207 + 24 66 44 | 7290 14052 | 180444 357308 + 25 69 46 | 25381 49667 | 898310 1787611 + 26 72 48 | 91441 180502 | 4532719 9042238 + 27 75 50 | 329824 654674 | 22949165 45839601 + 28 78 52 | 1204737 2398527 | 116805726 233457359 + 29 81 54 | 4412031 8800984 | 596228948 1192066180 + 30 84 56 | 16248772 32447008 | 3052696452 6104366484 + 31 87 58 | 59995535 119883207 | 15667197926 31331752928 + 32 90 60 | 222231424 444226539 | 80591725752 161176530535 + 33 93 62 | 825028656 1649550311 | 415411427833 830804928594 + 34 96 64 | 3069993552 6138874486 | 2145396827091 4290746578254 + 35 99 66 | 11446245342 22890091062 | 11100060860777 22199999305869 + 36 102 68 | 42758608761 85511947468 | + 37 105 70 | 160012226334 320013030067 | + 38 108 72 | 599822851579 1199620598580 | + 39 111 74 | 2252137171764 4504219709753 | + 40 114 76 | 8469193859271 16938267502048 | + + A previous version of this table had the nv=29 value 8800984 incorrect + for unknown reasons. It does seem that the program always got the + right answer. + + ---------------------------------------------------------------- + + 3-connected plane quadrangulations (plantri -q). + + quadrangulations + + nv ne nf all O-P + + 8 12 6 | 1 1 + 9 14 7 | 0 0 + 10 16 8 | 1 1 + 11 18 9 | 1 1 + 12 20 10 | 3 4 + 13 22 11 | 3 3 + 14 24 12 | 11 15 + 15 26 13 | 18 25 + 16 28 14 | 58 92 + 17 30 15 | 139 234 + 18 32 16 | 451 803 + 19 34 17 | 1326 2469 + 20 36 18 | 4461 8512 + 21 38 19 | 14554 28290 + 22 40 20 | 49957 98148 + 23 42 21 | 171159 338673 + 24 44 22 | 598102 1188338 + 25 46 23 | 2098675 4180854 + 26 48 24 | 7437910 14840031 + 27 50 25 | 26490072 52904562 + 28 52 26 | 94944685 189724510 + 29 54 27 | 341867921 683384218 + 30 56 28 | 1236864842 2472961423 + 31 58 29 | 4493270976 8984888982 + 32 60 30 | 16387852863 32772085447 + 33 62 31 | 59985464681 119963084542 + 34 64 32 | 220320405895 440623586740 + 35 66 33 | 811796327750 1623555117611 + 36 68 34 | 3000183106119 6000283550482 + + (In a previous version of this table, the two values for nv=31 were + interchanged. Thanks to Hugo Pfoertner for noticing.) + + ---------------------------------------------------------------- + + General quadrangulations (plantri -Q) + + nv ne nf all O-P + + 3 2 1 | 1 1 + 4 4 2 | 3 3 + 5 6 3 | 7 7 + 6 8 4 | 30 33 + 7 10 5 | 124 156 + 8 12 6 | 733 1070 + 9 14 7 | 4586 7515 + 10 16 8 | 33373 59151 + 11 18 9 | 259434 483925 + 12 20 10 | 2152298 4136964 + 13 22 11 | 18615182 36416865 + 14 24 12 | 166544071 329048627 + 15 26 13 | 1528659536 3037029030 + 16 28 14 | 14328433429 28553451498 + 17 30 15 | 136649176084 272766018806 + 18 32 16 | 1322594487342 2642420298576 + 19 34 17 | 12965736092988 25916954091582 + 20 36 18 | 128543259338048 257009789443925 + + ---------------------------------------------------------------- + + Appolonian networks. + + nv ne nf all O-P + + 4 6 4 | 1 1 + 5 9 6 | 1 1 + 6 12 8 | 1 1 + 7 15 10 | 3 4 + 8 18 12 | 7 10 + 9 21 14 | 24 40 + 10 24 16 | 93 171 + 11 27 18 | 434 831 + 12 30 20 | 2110 4147 + 13 33 22 | 11002 21822 + 14 36 24 | 56713 116062 + 15 39 26 | 321776 642600 + 16 42 28 | 1792133 3582322 + 17 45 30 | 10131027 20256885 + 18 48 32 | 57949430 115888201 + 19 51 34 | 334970205 669911568 + 20 54 36 | 1953890318 3907720521 + 21 57 38 | 11489753730 22979343010 + 22 60 40 | 68054102361 136107859377 + 23 63 42 | 405715557048 811430160282 + + ---------------------------------------------------------------- + +APPENDIX F. Version History + +The original edition of plantri, which performed only a few of the +functions of the current edition, was released in June 1996. Here +we will list the changes made in the functionality of recent editions +only. Internal changes are listed in plantri.c. + +Version 3.0: + Released on April 25, 2000. + +Version 3.1: + Released on July 3, 2000. + + It was discovered by Thom Sulanke that the code for simple + triangulations stopped working correctly at 26 or more vertices. + The bug does not affect any of the calculation sizes listed in + Appendix E. We believe that the only possible way of encountering + the bug with the distributed software was to use the maxdeg or + allowed_deg programs for 26 or more vertices. Correct operation + with -m4, -c4, -b and the min5 plugin was not affected. + + Version 3.1 corrects the bug without otherwise changing program + behaviour. Many thanks to Thom for his assistance. + +Version 4.0: + Released on April 20, 2001. + + Added -q for 3-connected quadrangulations. + Added -pc1 and -pc2 for general plane graphs. + Added -m5 and variants. The plug-in min5.c is no longer required. + sparse6 output now represents loops only once. + +Version 4.1: + Released on November 30, 2001. + + Added -qc2, -qc4, -qm2c2 for types of quadrangulation. + +Version 4.3: + Released on August 5, 2007. + + Added -V : write only those with non-trivial groups + Added -E : write output in edge code + Added -bp : general bipartite graphs + -p can now make graphs of 2 or 3 vertices + +Version 4.4: + Released on May 2, 2009. + + Fixed -pc1x and -pc2x + Fixed incorrect connectivity computation in -p and -pb, + only known problems were with -c1x, -c2x and statistics + reported by -v + +Version 4.5: + Released on September 5, 2011. + + Also apply FAST_FILTER_* to starting graphs (all uses need checking + against the code as more than one filter might need defining) + +Version 4.6: + Minor internal changes only. + +Version 4.7: + Released on March 8, 2014. + + Added Appolonian graphs. + +Version 5.0: + Released on October 2, 2016. + + Added 4-connected polytopes (-pc4). + +Version 5.2: + Released on February 28, 2018. + + Added -E for text edgecode output. + Fixed case -m4c3x which didn't work as advertised. + Fixed the group of the gyro (triangulation with 3 vertices and one loop). + Readjusted all splitting levels. + +Version 5.3: + Released on May 17, 2022. + + An error in splitting for cases -q and -pb could cause some graphs + to be output multiple times in version 5.2 (but not earlier). + Also removed erroneous interpretation of CLOCKS_PER_SEC. + +Version 5.4: + Released on March 10, 2023. + + -Q was added for general quadrangulations. + +Version 5.5: + Released on May 17, 2024. + + Fixed splitting for trivial sizes of -p (2 or 3 vertices). + + ---------------------------------------------------------------- + +APPENDIX G. Copyright and license + +This is the copyright statement for plantri and associated utilities. + +Copyright is jointly held by the authors + Gunnar Brinkmann, University of Gent, gunnar.brinkmann@ugent.be + Brendan McKay, Australian National University, brendan.mcKay@anu.edu.au + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this software except in compliance with the License. +A copy of the License is included in the package and you can also +view it at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/apn/lean/docs/polymake/LICENSE b/apn/lean/docs/polymake/LICENSE new file mode 100644 index 00000000..6eda76f4 --- /dev/null +++ b/apn/lean/docs/polymake/LICENSE @@ -0,0 +1,361 @@ +************************************************************************ +* The GNU General Public License cited below applies to the * +* entire polymake code written in whatever programming language. * +* * +* There are, however, parts of third-party software included in this * +* distribution with the solely aim to make the installation process * +* easier. Most are protected by GPL too, but for some packages * +* other open source licenses apply. In any case, free non-commercial * +* use and redistribution are allowed without restrictions. * +* * +* Please refer to the appropriate copyright notices in the * +* external/* subdirectories for details. * +* * +* Please note also, that for the sake of reducing the distribution * +* size, the bundled packages do not contain tutorials, examples, * +* documentation, or other components not used by polymake. You may * +* obtain them, if needed, directly from the original websites. * +************************************************************************ + + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place - Suite 330 + Boston, MA 02111-1307, USA. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) 19yy + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; see the file COPYING. If not, write to + the Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/apn/lean/docs/polymake/polymake.md b/apn/lean/docs/polymake/polymake.md new file mode 100644 index 00000000..1070ea7e --- /dev/null +++ b/apn/lean/docs/polymake/polymake.md @@ -0,0 +1,1872 @@ + + +# polymake 4.6 usage + +Start the interactive shell with `polymake`. Run a script non-interactively with `polymake --script ` (see the Scripting section at the end). The shell language is polymake/Perl. + +# Using Perl within polymake + +The language that the interactive version of `polymake` speaks is a dialect of Perl that we refer to as `polymake`/Perl. See [www.perl.org](http://www.perl.org) for comprehensive Perl information. Note also that the ordinary Perl manual pages are particularly useful, especially the perlintro man page which is also available on [perldoc](http://perldoc.perl.org/perlintro.html). This short section here cannot be a replacement for a thorough introduction to this language, but we want to focus on a few key points that are relevant to `polymake`. + +### Standard data structures + +The Perl programming language originally provides three different data structures, scalars(`$`), arrays(`@`), and hashes(`%`). The user always has to specify the type of a variable using the appropriate symbol `$`, `@`, or `%`. If you forget to do so, you will receive the following error message: + + > i=5; + polymake: ERROR: Unquoted string "i" may clash with future reserved word. + + + + + +Here are some simple commands illustrating how to use the different data structures: +##### Scalars + + +```perl +$i=5; +$j=6; +$sum=$i+$j; print $sum; +``` +Output: +``` +11 +``` + + +##### Arrays + + + + +```perl +@array=("a","b","c"); print scalar(@array); +push(@array,"d"); print "@array"; +$first_entry=$array[0]; print $first_entry; +print join("\n",@array); +@array2=(3,1,4,2); +print sort(@array2); +``` +Output: +``` +3a b c daa +b +c +d1234 +``` + + +##### Hashes + + + + +```perl +%hash=(); +$hash{"zero"}=0; +$hash{"four"}=4; +print keys %hash; +print join(", ",keys %hash); +print join(", ",values %hash); +%hash=("one",1,"two",2); +%hash=("one"=>1,"two"=>2); +``` +Output: +``` +fourzerofour, zero4, 0 +``` + + +### `polymake`-Perl + +In addition to the three standard data structures, the enriched version of `Perl` used in `polymake` also provides special data structures for dealing with more complicated concepts. For an introduction to the polymake object model see [here](properties.ipynb#Objects). + +`polymake`'s object hierarchy is completely reflected on the Perl side. Let us create a small polytope as an example object. + + + + +```perl +$p = new Polytope(POINTS=>[[1,0,1],[1,0,-1],[1,1,0],[1,-1,0]]); +``` + + +Note that the `Perl`-type of the variable `$p` is `Scalar`, as the variable is internally treated as a reference to a `C++`-object. The true nature of the object becomes visible if it is printed: + + + + +```perl +print $p; +``` +Output: +``` +Polymake::polytope::Polytope__Rational=ARRAY(0x55c8aa54c778) +``` + +In this case it is a `polymake` object from the application `polytope`, and it happens to be of type `Polytope`. Technically, `$p` is a reference to an array (but it should be never treated as an array unless you are deliberately trying to crash `polymake`). If you want less technical information on the type of your object, use this: + +```perl +print $p->type->full_name; +``` +Output: +``` +Polytope +``` + + +#### "Small objects": Data structures inherited from C++ + +You can use objects that are inherited from the `C++`-side of `polymake` in the interactive shell. A complete list of so-called "small objects" can be found in the [online documentation](https://polymake.org/doku.php/documentation/latest/common#property_types). +Here is a selection of three different structures that facilitate everyday work with `polymake`: +##### Arrays + +The small object `Array` can be initialized in different ways and with different template parameters: + + + + +```perl +@array=("a","b","c"); +$arr1=new Array(\@array); print $arr1; +$arr2=new Array([3,2,5]); print $arr2; +$arr3=new Array(0,1,2,3); print $arr3; +$arr4=new Array(0..4); print $arr4; +$arr5=new Array($arr4); print $arr5; +``` +Output: +``` +a b c3 2 50 1 2 30 1 2 3 40 1 2 3 4 +``` + + +You have random access: + + + + +```perl +$arr5->[0] = 100; +print $arr5; +``` +Output: +``` +100 1 2 3 4 +``` + + It is also possible to convert the `C++`-object `Array` into a `Perl`-array by writing + + + + +```perl +@arr4=@{$arr4}; print $arr2; +``` +Output: +``` +3 2 5 +``` + + + or simply + + + + +```perl +@arr4=@$arr4; +``` + + +##### Sets + +On `C++`-side sets are stored in a balanced binary search (AVL) tree. For more information see the [PTL-documentation](https://polymake.org/release_docs/master/PTL/classpm_1_1Set.html). In many cases, the small objects can be converted into `Perl`-types in the expected way: + + + + +```perl +$set=new Set(3,2,5); print $set; +print $set->size; +@array_from_set=@$set; +``` +Output: +``` +{2 3 5}3 +``` + + +##### Matrices + +Here is a simple way to initialize a matrix: + + + + +```perl +$mat=new Matrix([[2,1,4,0,0],[3,1,5,2,1],[1,0,4,0,6]]); +print $mat; +``` +Output: +``` +2 1 4 0 0 +3 1 5 2 1 +1 0 4 0 6 +``` + + + You could also define it by passing a reference to an (`Perl`-)array of `Vectors`. The single entries are interpreted as different rows: + + + + +```perl +$row1=new Vector([2,1,4,0,0]); +$row2=new Vector([3,1,5,2,1]); +$row3=new Vector([1,0,4,0,6]); +@matrix_rows=($row1,$row2,$row3); +$matrix_from_array=new Matrix(\@matrix_rows); +``` + + + You can change a single entry of a matrix in the following way (if it is not already assigned to an immutable property like `VERTICES`!): + + + + +```perl +$mat->row(1)->[1]=7; +print $mat->row(1)->[1], "\n"; +print $mat, "\n"; +$mat->elem(1,2)=8; +print $mat; +``` +Output: +``` +7 +2 1 4 0 0 +3 7 5 2 1 +1 0 4 0 6 + +2 1 4 0 0 +3 7 8 2 1 +1 0 4 0 6 +``` + + + A unit matrix of a certain dimension can be defined via the user-function `unit_matrix(.)`: + + + + +```perl +$unit_mat=4*unit_matrix(3); +print $unit_mat; +``` +Output: +``` +(3) (0 4) +(3) (1 4) +(3) (2 4) +``` + + + The reason for the "strange output" is the implementation as *sparse matrix*: + + + + +```perl +print ref($unit_mat); +``` +Output: +``` +Polymake::common::SparseMatrix_A_Rational_I_NonSymmetric_Z +``` + + +However, some functions cannot deal with this special type of matrix. In this case it is necessary to transform the sparse matrix into a dense matrix first via: + + + + +```perl +$dense=new Matrix($unit_mat);print $dense; +``` +Output: +``` +4 0 0 +0 4 0 +0 0 4 +``` + + + or just + + + + +```perl +$dense2=dense($unit_mat);print $dense2; +``` +Output: +``` +4 0 0 +0 4 0 +0 0 4 +``` + + + You can also work with matrices that have different types of coordinates like `Rational`, `Float`, or `Int`: + + + + +```perl +$m_rat=new Matrix(3/5*unit_matrix(5)); print $m_rat, "\n"; +$m2=$mat/$m_rat; print $m2, "\n"; +$m_int=new Matrix(unit_matrix(5)); print $m_int, "\n"; +``` +Output: +``` +3/5 0 0 0 0 +0 3/5 0 0 0 +0 0 3/5 0 0 +0 0 0 3/5 0 +0 0 0 0 3/5 + +2 1 4 0 0 +3 7 8 2 1 +1 0 4 0 6 +3/5 0 0 0 0 +0 3/5 0 0 0 +0 0 3/5 0 0 +0 0 0 3/5 0 +0 0 0 0 3/5 + +1 0 0 0 0 +0 1 0 0 0 +0 0 1 0 0 +0 0 0 1 0 +0 0 0 0 1 +``` + +Sometimes there is incompatible types: +```perl +> $m3=$m_rat/$m_int; +``` +``` +C++/perl Interface module compilation failed; most likely due to a type mismatch. +Set the variable $Polymake::User::Verbose::cpp to a positive value and repeat for more details. +``` + +The error message indicates that you need to convert the integer matrix to a rational matrix first: + +```perl +$m3=$m_rat/(convert_to($m_int)); print $m3; +``` +Output: +``` +3/5 0 0 0 0 +0 3/5 0 0 0 +0 0 3/5 0 0 +0 0 0 3/5 0 +0 0 0 0 3/5 +1 0 0 0 0 +0 1 0 0 0 +0 0 1 0 0 +0 0 0 1 0 +0 0 0 0 1 +``` + + + By "/" you can add rows to a matrix, whereas "|" adds columns. By the way, this also works for `Vector`. + + + + +```perl +$z_vec=zero_vector($m_int->rows); +$extended_matrix=($z_vec|$m_int); print $extended_matrix; +``` +Output: +``` +0 1 0 0 0 0 +0 0 1 0 0 0 +0 0 0 1 0 0 +0 0 0 0 1 0 +0 0 0 0 0 1 +``` + + +It is also possible to nest template parameters in any way you like, e.g. + + + + +```perl +$set=new Set(3,2,5); +$template_Ex=new Array>((new Set(5,2,6)),$set); print $template_Ex; print ref($template_Ex); +``` +Output: +``` +{2 5 6} +{2 3 5} +Polymake::common::Array__Set__Int +``` + + +However, if you use a template combination, you have never used before, it may take some time until you see the result. This is due to the fact that `polymake` compiles your new combination *on the fly*. But this is only a one-time effect, and next time you use this combination it will work without delay. + +#### "Big Objects": Objects with properties + +A big object is an instance of a data type which represents a mathematical concept with clear semantics. They may have template parameters. + + + + +```perl +$p=new Polytope(POINTS=>cube(4)->VERTICES); +$lp=new LinearProgram(LINEAR_OBJECTIVE=>[0,1,1,1,1]); +``` + + +Big objects have properties which come with a type, which is either built-in or a small object type or a big object type, and which can be accessed using the `-``>` operator. + + + + +```perl +# access the property named `LP`: +$p->LP=$lp; +# properties can have properties themselves. +print $p->LP->MAXIMAL_VALUE; +``` +Output: +``` +4 +``` + + + +Scalar properties can be used in arithmetic expressions right away. + + + + +```perl +$i = ($p->N_FACETS * $p->N_FACETS) * 15; +``` + + + + +```perl +print $i; +``` +Output: +``` +960 +``` + +Check out the tutorial on [properties](properties.ipynb) to learn more about the way properties are used and computed. + +### A small example script... + +...to demonstrate the usage of `polymake`/Perl. You can download the matrix file [here](https://polymake.org/lib/exe/fetch.php/points.demo). + + + +```perl +### load matrix from file +open(INPUT, "< demo/Workshop2011/points.demo"); +$matrix=new Matrix(); +close(INPUT); +print $matrix; + + +### create a polytope from the matrix +$p=new Polytope(POINTS=>$matrix); +print $p->FACETS; +print $p->DIM; +print $p->VERTEX_SIZES; + + +### print "simple" vertices +for(my $i=0;$iVERTEX_SIZES});$i++){ + if($p->VERTEX_SIZES->[$i]==$p->DIM){ + print $i.": ".$p->VERTICES->row($i)."\n"; + } +} + + +### put their indices in a set +$s=new Set(); +for(my $i=0;$iVERTEX_SIZES});$i++){ + if($p->VERTEX_SIZES->[$i]==$p->DIM){ + $s+=$i; + } +} + + +### iterate the set in two different ways +foreach(@{$s}){ + print $p->VERTICES->row($_)."\n"; +} +foreach my $index(@{$s}){ + print $p->VERTICES->row($index)."\n"; +} + + +### create a minor of the vertices matrix that only contains the simple ones +$special_points=$p->VERTICES->minor($s,All); print $special_points; +``` +Output: +``` +-1 +``` + +### Writing scripts + +Comprehensive information on how to use scripts within `polymake` can be found [here](https://polymake.org/doku.php/user_guide/howto/scripting). + +# Tutorial on Polytopes + +A *polytope* is the convex hull of finitely many points in some Euclidean space. Equivalently, a polytope is the bounded intersection of finitely many affine halfspaces. `polymake` can deal with polytopes in both representations and provides numerous tools for analysis. + + +This tutorial first shows basic ways of defining a polytope from scratch. For larger input (e.g. from a file generated by some other program) have a look at our HowTo on [loading data](data.ipynb) in `polymake`. + + +The second part demonstrates some of the tool `polymake` provides for handling polytopes by examining a small example. For a complete list of properties of polytopes and functions that `polymake` provides, see the [polytope documentation](https://polymake.org/doku.php/documentation/latest/polytope). + +## Constructing a polytope from scratch + + +### V-Description + +To define a polytope as the convex hull of finitely many points, you can pass a matrix of coordinates to the constructor. Since `polymake` uses [homogeneous coordinates](coordinates.ipynb), you need to set the additional coordinate x0 to 1. + + +```perl +$p = new Polytope(POINTS=>[[1,-1,-1],[1,1,-1],[1,-1,1],[1,1,1],[1,0,0]]); +``` + + +The `POINTS` can be any set of coordinates, they are not required to be irredundant nor vertices of their convex hull. To compute the actual vertices of our polytope, we do this: + + + + +```perl +print $p->VERTICES; +``` +Output: +``` +1 -1 -1 +1 1 -1 +1 -1 1 +1 1 1 +``` + +You can also add a lineality space via the input property `INPUT_LINEALITY`. + + + + +```perl +$p2 = new Polytope(POINTS=>[[1,-1,-1],[1,1,-1],[1,-1,1],[1,1,1],[1,0,0]],INPUT_LINEALITY=>[[0,1,0]]); +``` + + +To take a look at what that thing looks like, you can use the `VISUAL` method: + + + + +```perl +$p2->VISUAL; +``` + + +See [here](visual_tutorial.ipynb#application-polytope) for details on visualizing polytopes. + + If you are sure that all the points really are *extreme points* (vertices) and your description of the lineality space is complete, you can define the polytope via the properties `VERTICES` and `LINEALITY_SPACE` instead of `POINTS` and `INPUT_LINEALITY`. This way, you can avoid unnecessary redundancy checks. + + + + The input properties `POINTS` / `INPUT_LINEALITY` may not be mixed with the properties `VERTICES` / `LINEALITY_SPACE`. Furthermore, the `LINEALITY_SPACE` **must be specified** as soon as the property `VERTICES` is used: + + + + +```perl +$p3 = new Polytope(VERTICES=>[[1,-1,-1],[1,1,-1],[1,-1,1],[1,1,1]], LINEALITY_SPACE=>[]); +``` + + +### H-Description + +It is also possible to define a polytope as an intersection of finitely many halfspaces, i.e., a matrix of inequalities. + + + +An inequality a0 + a1 x1 + ... + ad xd >= 0 is encoded as a row vector (a0,a1,...,ad), see also [Coordinates for Polyhedra](coordinates.ipynb). Here is an example: + + + + +```perl +$p4 = new Polytope(INEQUALITIES=>[[1,1,0],[1,0,1],[1,-1,0],[1,0,-1],[17,1,1]]); +``` + + +To display the inequalities in a nice way, use the `print_constraints` method. + + + + +```perl +print_constraints($p4->INEQUALITIES); +``` +Output: +``` +0: x1 >= -1 +1: x2 >= -1 +2: -x1 >= -1 +3: -x2 >= -1 +4: x1 + x2 >= -17 +5: 0 >= -1 +``` + +The last inequality means 17+x1+x2 >= 0, hence it does not represent a facet of the polytope. If you want to take a look at the acutal facets, do this: + + + + +```perl +print $p4->FACETS; +``` +Output: +``` +1 1 0 +1 0 1 +1 -1 0 +1 0 -1 +``` + + +If your polytope lies in an affine subspace then you can specify its equations via the input property `EQUATIONS`. + + + + + + +```perl +$p5 = new Polytope(INEQUALITIES=>[[1,1,0,0],[1,0,1,0],[1,-1,0,0],[1,0,-1,0]],EQUATIONS=>[[0,0,0,1],[0,0,0,2]]); +``` + + +Again, if you are sure that all your inequalities are facets, you can use the properties `FACETS` and `AFFINE_HULL` instead. Note that this pair of properties is dual to the pair `VERTICES` / `LINEALITY_SPACE` described above. + + +## Convex Hull Computations + +Of course, `polymake` can convert the V-description of a polytope to its H-description and vice versa. In fact, this is done automatically whenever you ask for a suitable property. + +For instance, continuing with the example above, the following triggers a dual convex hull computation. Note that this particular command does not compute any output. + +```perl +$p5->VERTICES; +``` + +Printing the vertices later does *not* result in a recomputation. Known properties are stored. + +```perl +print $p5->VERTICES; +``` +Output: +``` +1 1 -1 0 +1 1 1 0 +1 -1 1 0 +1 -1 -1 0 +``` + +Depending on the individual configuration polymake chooses one of the several convex hull computing algorithms that have a `polymake` interface. Available algorithms are double description ([cdd](http://www.ifor.math.ethz.ch/~fukuda/cdd_home/cdd.html) of [ppl](http://bugseng.com/products/ppl)), reverse search ([lrs](http://cgm.cs.mcgill.ca/~avis/C/lrs.html)), and beneath beyond (internal). It is also possible to specify explicitly which method to use by using the `prefer_now` command. Here we show a primal convex hull computaton, i.e., from V- to H-description, with lrs. + +```perl +prefer_now "lrs"; +$p = new Polytope(POINTS=>[[1,1],[1,0]]); +print $p->FACETS; +``` +Output: +``` +1 -1 +0 1 +``` + +Use `prefer` instead of `prefer_now` if you want to make this permanent. + +## A Neighborly Cubical Polytope + +`polymake` provides a variety of standard polytope constructions and transformations. This example construction introduces some of them. Check out the [documentation](https://polymake.org/doku.php/documentation/latest/polytope) for a comprehensive list. + +The goal is to construct a 4-dimensional cubical polytope which has the same graph as the 5-dimensional cube. It is an example of a *neighborly cubical* polytope as constructed in + + +* Joswig & Ziegler: Neighborly cubical polytopes. Discrete Comput. Geom. 24 (2000), no. 2-3, 325--344, [DOI 10.1007/s004540010039](http://www.springerlink.com/content/m73pqv6kr80rw4b1/) + +This is the entire construction in a few lines of `polymake` code: + + + + +```perl +$c1 = cube(2); +$c2 = cube(2,2); +$p1x2 = product($c1,$c2); +$p2x1 = product($c2,$c1); +$nc = conv($p1x2,$p2x1); +``` + + + +Let us examine more closely what this is about. First we constructed a square `$c1` via calling the function `cube`. The only parameter `2` is the dimension of the cube to be constructed. It is not obvious how the coordinates are chosen; so let us check. + + + + +```perl +print $c1->VERTICES; +``` +Output: +``` +1 -1 -1 +1 1 -1 +1 -1 1 +1 1 1 +``` + + +The four vertices are listed line by line in homogeneous coordinates, where the homogenizing coordinate is the leading one. As shown the vertices correspond to the four choices of `+/-1` in two positions. So the area of this square equals four, which is verified as follows: + + + + +```perl +print $c1->VOLUME; +``` +Output: +``` +4 +``` + + +Here the volume is the Euclidean volume of the ambient space. Hence the volume of a polytope which is not full-dimensional is always zero. + + + +The second polytope `$c2` constructed is also a square. However, the optional second parameter says that `+/-2`-coordinates are to be used rather than `+/-1` as in the default case. The optional parameter is also allowed to be `0`. In this case a cube with `0/1`-coordinates is returned. You can access the documentation of functions by typing their name in the `polymake` shell and then hitting F1. + + + +The third command constructs the polytope `$p1x2` as the cartesian product of the two squares. Clearly, this is a four-dimensional polytope which is combinatorially (even affinely) equivalent to a cube, but not congruent. This is easy to verify: + + + + +```perl +print isomorphic($p1x2,cube(4)); +``` +Output: +``` +true +``` + +```perl +print congruent($p1x2,cube(4)); +``` +Output: +``` +0 +``` + + +Both return values are boolean, represented by the numbers `1` and `0`, respectively. This questions are decided via a reduction to a graph isomorphism problem which in turn is solved via `polymake`'s interface to `nauty`. + + + +The polytope `$p2x1` does not differ that much from the previous. In fact, the construction is twice the same, except for the ordering of the factors in the call of the function `product`. Let us compare the first vertices of the two products. One can see how the coordinates are induced by the ordering of the factors. + + + + +```perl +print $p1x2->VERTICES->[0]; +``` +Output: +``` +1 1 -1 2 2 +``` + +```perl +print $p2x1->VERTICES->[0]; +``` +Output: +``` +1 2 -2 1 1 +``` + + +In fact, one of these two products is obtained from the other by exchanging coordinate directions. Thats is to say, they are congruent but distinct as subsets of Euclidean 4-space. This is why taking their joint convex hull yields something interesting. Let us explore what kind of polytope we got. + + + + +```perl +print $nc->SIMPLE, " ", $nc->SIMPLICIAL; +``` +Output: +``` +false false +``` + + +This says the polytope is neither simple nor simplicial. A good idea then is to look at the f-vector. Beware, however, this usually requires to build the entire face lattice of the polytope, which is extremely costly. Therefore this is computationally infeasible for most high-dimensional polytopes. + + + + +```perl +print $nc->F_VECTOR; +``` +Output: +``` +32 80 72 24 +``` + + +This is a first hint that our initial claim is indeed valid. The polytope constructed has 32 vertices and 80 = 32*5/2 edges, as many as the 5-dimensional cube: + + + + +```perl +print cube(5)->F_VECTOR; +``` +Output: +``` +32 80 80 40 10 +``` + + +What is left is to check whether the vertex-edge graphs of the two polytopes actually are the same, and if all proper faces are combinatorially equivalent to cubes. + + + + +```perl +print isomorphic($nc->GRAPH->ADJACENCY,cube(5)->GRAPH->ADJACENCY); +``` +Output: +``` +true +``` + +```perl +print $nc->CUBICAL; +``` +Output: +``` +true +``` + +See the [tutorial on graphs](apps_graph.ipynb) for more on that subject. + +# Objects, Properties and Rules + +### Objects +In polymake, there is two kinds of objects. A *Big Object* models a complex mathematical concept, like a Polytope or a SimplicialComplex, while a *small object* is an instance of one of the many data types commonly used in computer science, like Integers, Matrices, Sets or Maps. A big object consists of a collection of other objects (big or small) describing it, called *properties*, and functions to compute more properties from the ones already known, called *production rules*. + +To get a more detailed explanation of the `polymake` object model and properties, check out the [scripting guide](https://polymake.org/doku.php/user_guide/howto/scripting#most_important_interfaces). + +You can save polymake objects to disc, as explained [here](data.ipynb). + +### Properties + +Each (big) object has a list of properties of various types. When an object is 'born' it comes with an initial list of properties, and all other properties will be derived from those. Let's look at example from the `polytope` application. The following creates a 3-dimensional cube: + +```perl +$c=cube(3); +``` + +To find out what the initial set of properties is, use the `list_properties` method. It returns an array of strings. The extra code is just there to print this list nicely. + +```perl +print join(", ", $c->list_properties); +``` +Output: +``` +CONE_AMBIENT_DIM, CONE_DIM, FACETS, AFFINE_HULL, VERTICES_IN_FACETS, BOUNDED +``` + +To find out the type of the object `$c`, enter + +```perl +print $c->type->full_name; +``` +Output: +``` +Polytope +``` + + +To see what a property contains, use the `->` syntax: + + + + +```perl +print $c->FACETS; +``` +Output: +``` +1 1 0 0 +1 -1 0 0 +1 0 1 0 +1 0 -1 0 +1 0 0 1 +1 0 0 -1 +``` + + + 1 1 0 0 + 1 -1 0 0 + 1 0 1 0 + 1 0 -1 0 + 1 0 0 1 + 1 0 0 -1 + + +You can also get the content of all properties using the `properties` method: + + + + +```perl +$c->properties; +``` +Output: +``` +name: c +type: Polytope +description: cube of dimension 3 + + +AFFINE_HULL + + +BOUNDED +true + +CONE_AMBIENT_DIM +4 + +CONE_DIM +4 + +FACETS +1 1 0 0 +1 -1 0 0 +1 0 1 0 +1 0 -1 0 +1 0 0 1 +1 0 0 -1 + + +VERTICES_IN_FACETS +{0 2 4 6} +{1 3 5 7} +{0 1 4 5} +{2 3 6 7} +{0 1 2 3} +{4 5 6 7} +``` + +### Production Rules + +The object is changed if we ask for a property which has not been computed before. + +```perl +print $c->VERTICES; +``` +Output: +``` +1 -1 -1 -1 +1 1 -1 -1 +1 -1 1 -1 +1 1 1 -1 +1 -1 -1 1 +1 1 -1 1 +1 -1 1 1 +1 1 1 1 +``` + +```perl +print join(", ", $c->list_properties); +``` +Output: +``` +CONE_AMBIENT_DIM, CONE_DIM, FACETS, AFFINE_HULL, VERTICES_IN_FACETS, BOUNDED, FEASIBLE, POINTED, N_VERTICES, N_FACETS, VERTICES, LINEALITY_SPACE +``` + + +The property `VERTICES` was added, but a few others were computed on the way, too. `polymake` applied a sequence of *production rules* that add new properties to the object that can be computed from the properties the object already posesses. + +What properties *can* be computed for a given object depends on the set of rules defined for it. Here is a short sequence of commands which lets you find out. + + + + +```perl +$t=$c->type; +print join(", ", sorted_uniq(sort { $a cmp $b } map { keys %{$_->properties} } $t, @{$t->super})); +``` +Output: +``` +AFFINE_HULL, BALANCE, BALANCED, BOUNDARY_LATTICE_POINTS, BOUNDED, CANONICAL, CD_INDEX_COEFFICIENTS, CENTERED, CENTERED_ZONOTOPE, CENTRALLY_SYMMETRIC, CENTROID, CHIROTOPE, CIRCUITS, COCIRCUITS, COCIRCUIT_EQUATIONS, COCUBICAL, COCUBICALITY, COMBINATORIAL_DIM, COMPLEXITY, COMPRESSED, CONE_AMBIENT_DIM, CONE_DIM, CS_PERMUTATION, CUBICAL, CUBICALITY, CUBICAL_H_VECTOR, DEGREE_ONE_GENERATORS, DUAL_BOUNDED_H_VECTOR, DUAL_GRAPH, DUAL_H_VECTOR, EDGE_ORIENTABLE, EDGE_ORIENTATION, EHRHART_POLYNOMIAL, EHRHART_QUASI_POLYNOMIAL, EQUATIONS, EXCESS_RAY_DEGREE, EXCESS_VERTEX_DEGREE, F2_VECTOR, FACETS, FACETS_THRU_INPUT_RAYS, FACETS_THRU_POINTS, FACETS_THRU_RAYS, FACETS_THRU_VERTICES, FACET_SIZES, FACET_VERTEX_LATTICE_DISTANCES, FACET_VOLUMES, FACET_WIDTH, FACET_WIDTHS, FACE_SIMPLICITY, FAR_FACE, FAR_HYPERPLANE, FATNESS, FEASIBLE, FLAG_VECTOR, FOLDABLE_COCIRCUIT_EQUATIONS, FOLDABLE_MAX_SIGNATURE_UPPER_BOUND, FTR_CYCLIC_NORMAL, FTV_CYCLIC_NORMAL, FULL_DIM, F_VECTOR, FacetPerm, FacetPerm.pure, GALE_TRANSFORM, GALE_VERTICES, GORENSTEIN, GORENSTEIN_CONE, GORENSTEIN_INDEX, GORENSTEIN_VECTOR, GRAPH, GROEBNER_BASIS, GROUP, G_VECTOR, HASSE_DIAGRAM, HILBERT_BASIS_GENERATORS, HILBERT_SERIES, HOMOGENEOUS, H_STAR_VECTOR, H_VECTOR, INEQUALITIES, INEQUALITIES_THRU_RAYS, INEQUALITIES_THRU_VERTICES, INPUT_LINEALITY, INPUT_RAYS, INPUT_RAYS_IN_FACETS, INPUT_RAY_LABELS, INTERIOR_LATTICE_POINTS, INTERIOR_RIDGE_SIMPLICES, LATTICE, LATTICE_BASIS, LATTICE_CODEGREE, LATTICE_DEGREE, LATTICE_EMPTY, LATTICE_POINTS_GENERAT +... [output truncated] +``` + + + +Instead of showing the (lengthy) enumeration have a look at the [documentation](https://polymake.org/doku.php/documentation/latest/polytope) for a complete list of properties known for objects of the application `polytope`. + + +#### Schedules + +You may wonder what sequence of rules led to the computation of a property you request. There usually are several mathematical ways to compute a property. `polymake` uses a nice scheduling algorithm to find the most efficient procedure, and you can look at what it returns. + +Suppose we want to see which sequence of rules leads to the computation of the F_VECTOR. + + + + +```perl +$schedule=$c->get_schedule("F_VECTOR"); +print join("\n", $schedule->list); +``` +Output: +``` +LINEALITY_DIM : LINEALITY_SPACE +COMBINATORIAL_DIM : CONE_DIM, LINEALITY_DIM +precondition : COMBINATORIAL_DIM ( F_VECTOR : N_FACETS, N_RAYS, COMBINATORIAL_DIM ) +F_VECTOR : N_FACETS, N_RAYS, COMBINATORIAL_DIM +``` + +So if you ask for the f-vector, `polymake` will first compute the dimension of the lineality space from the basis of the lineality space, then compute the combinatorial dimension from the lineality and cone dimensions, and then compute the f-vector from the number of facets, number of rays, and combinatorial dimension of the polytope. Applying the schedule to the object yields the same as asking for the property right away: + +```perl +$schedule->apply($c); +print join(", ", $c->list_properties); +``` +Output: +``` +CONE_AMBIENT_DIM, CONE_DIM, FACETS, AFFINE_HULL, VERTICES_IN_FACETS, BOUNDED, FEASIBLE, POINTED, N_VERTICES, N_FACETS, VERTICES, LINEALITY_SPACE, LINEALITY_DIM, COMBINATORIAL_DIM, F_VECTOR +``` + +As you can see, the things `polymake` needed to compute in order to get to the f-vector are stored in the object as well, so you don't have to recompute them later. + +If you're interested, read more about rule scheduling in the [scripting guide](https://polymake.org/doku.php/user_guide/howto/scripting#rule_planning) and the article on [writing rules yourself](https://polymake.org/doku.php/user_guide/extend/rulefiles). + +# Tutorial for Lattice Polytopes + +This page gives a small introduction to lattice polytopes in `polymake`, some useful external software, and usage hints for it. For a list of methods and properties applicable to lattice polytopes see [here](https://polymake.org/doku.php/user_guide/lattice_polytopes_doc). For an introduction to the `polymake` package see [here](https://polymake.org/doku.php/user_guide/start). + + +`polymake` always assumes that the lattice used to define a lattice polytope is the standard lattice Zd. Some rules also require that the polytope is full dimensional. There are user functions that transform a polytope sitting in some affine subspace of Rd into a full dimensional polytope, either in the induced lattice or the lattice spanned by the vertices, see below. + + + +## Dependence on other Software + +For some computations `polymake` has no built-in commands and passes the computation to external software. Currently, polymake has an interface to the following packages that compute various properties of lattice polytopes. + +* [libnormaliz](http://www.math.uos.de/normaliz/) by Winfried Bruns and Bogdan Ichim, bundled with polymake + +* [4ti2](http://www.4ti2.de/) by the 4ti2 team + +* [LattE macchiato](http://www.math.ucdavis.edu/~mkoeppe/latte/) by Matthias Köppe, building on `LattE` by Jesus de Loera et. al. + +* ([barvinok](http://freshmeat.net/projects/barvinok) by Sven Verdoolaege) + +Unless you want to deal with Hilbert bases of cones you don't need them. If you do, either the bundled extension `libnormaliz` or the external package `4ti2` suffices to do most computations with lattice polytopes. Computation of Gröbner bases currently requires `4ti2`. `LattE` only counts lattice points in a polytope and computes its Ehrhart polynomial, but may be faster on that than any other methods implemented. `barvinok` can be used to compute the number of lattice points and the h-polynomial. Access to barvinok is realized via an extension which has to be downloaded separately. + + For some of the commands in this tutorial you will need at least one of `bundled:libnormaliz` enabled or `4ti2` installed on your machine. We'll remind you at the relevant places. + + + +## Lattice Points in Rational Polytopes + +We start by creating a rational polytope using one of `polymake`'s standard polytope constructions. We choose the 3-dimensional cube with coordinates +1 and -1. So we start `polymake` at the command line and assign a cube to the variable $p. + + +```perl +$p=cube(3); +``` + + +Suppose we want to know how many lattice points this cube contains. The answer is of course already known, as the cube has one relative interior integral point per non-empty face. So we expect to get the answer 27. + + + + +```perl +print $p->N_LATTICE_POINTS; +``` +Output: +``` +27 +``` + +To satisfy this request, `polymake` computes all properties necessary to call an external program that provides the number of lattice points. In this case, `polymake` has passed the request to `lattE`, which is shown by the credit message that appears before the answer. By default, credits for external software are shown when an external package is used for the first time. You can change this behavior using the variable `$Verbose::credits`. If you don't have a version of `LattE`, or if you have set different preferences, then `polymake` may choose one of the other programs. So the credit statement depends on your configuration. + + +We can of course also ask `polymake` to compute the integral points for us. For our next computations we are only interested in the integral points in the interior of the cube, so we ask for + + + + +```perl +print $p->INTERIOR_LATTICE_POINTS; +``` +Output: +``` +1 0 0 0 +``` + +Internally, `polymake` computes the intersection of the polytope with the integer lattice, and then checks which of the points lies on a facet of $p. By default, `polymake` uses a project-and-lift algorithms to enumerate the lattice points. Note that our call to `LattE` above has only computed the number of integral points (which is done with an improved version of Barvinok's algorithm), so `polymake` really has to compute something here. If we had asked for `INTERIOR_LATTICE_POINTS` first, then `N_LATTICE_POINTS` would just have counted the rows of a matrix, which would have been much faster. So computation time can depend on the history. + +You can also ask for the HILBERT_BASIS, though in the case of a cube the result is not so exciting: + + + + +```perl +print $p->HILBERT_BASIS; +``` +Output: +``` +1 -1 -1 -1 +1 -1 -1 0 +1 -1 -1 1 +1 -1 0 -1 +1 -1 0 0 +1 -1 0 1 +1 -1 1 -1 +1 -1 1 0 +1 -1 1 1 +1 0 -1 -1 +1 0 -1 0 +1 0 -1 1 +1 0 0 -1 +1 0 0 0 +1 0 0 1 +1 0 1 -1 +1 0 1 0 +1 0 1 1 +1 1 -1 -1 +1 1 -1 0 +1 1 -1 1 +1 1 0 -1 +1 1 0 0 +1 1 0 1 +1 1 1 -1 +1 1 1 0 +1 1 1 1 +``` + +`polymake` has no native method to compute a Hilbert basis, so it has passed the computation to `4ti2`. The choice may vary, depending on what is installed on your computer (and configured for `polymake`). You can influence the choice with the appropriate `prefer` statement. + +Note that so far these commands also work for rational polytopes. + +## Lattice Polytopes + +Now we want to do some computations that don't make sense for polytopes that have non-integral vertex coordinates. We can let `polymake` check that our cube is indeed a polytope with integral vertices. + + + + +```perl +print $p->LATTICE; +``` +Output: +``` +true +``` + +A particularly interesting class of lattice polytopes is that of reflexive polytopes. A polytope is *reflexive* if its polar is agein alattice polytope. This implies in particular that the origin is the unique interior lattice point in the polytope. So, as we have seen above, our cube is a candidate. But this is not sufficient, so we have to do further checks. + + +Reflexivity is a property that is not defined for polytopes with non-integral vertices. So if we ask for it in `polymake`, then `polymake` checks that the entered polytope is indeed a lattice polytope (i.e. it is **bounded** and has **integral vertices**). In that case the object will automatically get the specialization `Polytope::Lattice`. + +```perl +print $p->REFLEXIVE; +``` +Output: +``` +true +``` + +Lattice polytopes can be used to define toric varieties with an ample line bundle, and many properties of the variety are reflected by the polytope. here is an example: The toric variety defined by our cube is *smooth*, i.e. it is one of the *smooth toric Fano varieties*. In `polymake`, we can just ask for this property in the following way. + +```perl +print $p->SMOOTH; +``` +Output: +``` +true +``` + + +The number of integral points in the k-th dilate of a polytope is given by a polynomial of degree d in k. This is the famous *Ehrhart Theorem*. In `polymake` you can obtain the coefficients of this polynomial (starting with the constant coefficient). + + + + +```perl +print $p->EHRHART_POLYNOMIAL; +``` +Output: +``` +8*x^3 + 12*x^2 + 6*x + 1 +``` + +`polymake` has passed this request to `LattE` or `normaliz`, but as we have used these programs already the credit message is suppressed (but if you save the cube to a file, then you will find it in there). Some coefficients of this polynomial have a geometric interpretation. E.g., the highest coefficient is the Euclidean volume of the polytope. + + + + +```perl +print $p->VOLUME; +``` +Output: +``` +8 +``` + +By a theorem of Stanley, the generating function for the number of lattice points can be written as the quotient of a polynomial h(t) by (1-t)d+1, and this polynomial has non-negative integral coefficients. + + + + +```perl +print $p->H_STAR_VECTOR; +``` +Output: +``` +1 23 23 1 +``` + +```perl +print $p->LATTICE_DEGREE; +``` +Output: +``` +3 +``` + +```perl +print $p->LATTICE_CODEGREE; +``` +Output: +``` +1 +``` + +In our case the coefficient vector is symmetric, as the polytope is reflexive. The *co-degree* of the polytope is d+1 minus the degree of the h-polynomial. It is the smallest factor by which we have to dilate the polytope to obtain an interior integral point. In our case, this is 1, as the cube already has an integral point. + + +We can obtain the volume of our polytope also from the `H_STAR_VECTOR`: Summing up the coefficients give the *lattice volume* of the polytope, which is d! times its Euclidean volume. + + + + +```perl +print $p->LATTICE_VOLUME; +``` +Output: +``` +48 +``` + + +Let us look at a different example: + + + + +```perl +$q=new Polytope(INEQUALITIES=>[[5,-4,0,1],[-3,0,-4,1],[-2,1,0,0],[-4,4,4,-1],[0,0,1,0],[8,0,0,-1],[1,0,-1,0],[3,-1,0,0]]); +``` + + +This actually defines a lattice polytope, which we can see from the list of vertices: + + + + +```perl +print $q->VERTICES; +``` +Output: +``` +1 3 1 7 +1 2 0 3 +1 3 0 7 +1 2 1 7 +1 2 0 4 +1 3 1 8 +1 3 0 8 +1 2 1 8 +``` + +`polymake` provides basically three methods for convex hull conversion, double description, reverse search, and beneath beyond. The first two are provided by the packages `cdd` and `lrs`, the last in internal. By default, `cdd` is chosen, and that is what was used above (they are bundled with `polymake`, you don't have to install them). A polytope Q is *normal* if every lattice point in the k-th dilate of Q is the sum of k lattice points in Q. You can check this property via + + + + +```perl +print $q->NORMAL; +``` +Output: +``` +false +``` + +So our polytope is not normal. We can also find a point that violates the condition. Being normal is equivalent to the fact, that the Hilbert basis of the cone C(Q) obtained from Q by embedding the polytope at height one and the coning over it has all its generators in height one. The property HILBERT_BASIS computes these generators: + + + + +```perl +print $q->HILBERT_BASIS; +``` +Output: +``` +1 2 0 3 +1 2 0 4 +1 2 1 7 +1 2 1 8 +1 3 0 7 +1 3 0 8 +1 3 1 7 +1 3 1 8 +2 5 1 13 +``` + +The last row is the desired vector: [2,5,1,13] is a vector in 2*Q, but it is not a sum of lattice points in Q. The cone C(Q) corresponds to an affine toric variety, and the above tells us that this variety is not normal. Yet, it is very ample, as we can check with + + + + +```perl +print $q->VERY_AMPLE; +``` +Output: +``` +true +``` + +Now assume we are particularly interested in the third facet of Q. We can pick this via + + + + +```perl +$f=facet($q,2); +``` + + +Recall that indexes in `polymake` start at 0, so the third facet has index 2. This is again a very ample polytope: + + + + +```perl +print $f->VERY_AMPLE; +``` +Output: +``` +true +``` + +The result is no surprise, being very ample is inherited by faces. We could also be interested in the facet width of the polytope `$f`. This is the minimum over the maximal distance of a facet to any other vertex. `polymake` knows how to compute this: + +```perl +#print $f->FACET_WIDTH; +``` + +Almost. It tells you that it can only do this for a full dimensional polytope, i.e. for a polytope whose dimension coincides with the ambient dimension. This is not true for our facet: It lives in the same ambient space as `$q`, but has one dimension less. We can remedy this by applying the following: + +```perl +$g=ambient_lattice_normalization($f); +print $g->FACET_WIDTH; +``` +Output: +``` +1 +``` + +The function `ambient_lattice_normalization` returns a full dimensional version of the polytope `$f` in the lattice induced by the intersection of the affine space of `$f` with Z^n. Now `$g` is full dimensional, and we can compute the facet width. Note that there is also a function which normalizes in the lattice spanned by the vertices of the polytope: `vertex_facet_normalization`. This can also be usefull for full dimensional polytopes. E.g. consider the cube we defined above. The sum of the entries of each vertex is odd, so the lattice spannd by the vertices is a sublattice of the integer lattice: + + + + +```perl +$cr=vertex_lattice_normalization($p); +print $cr->VERTICES; +``` +Output: +``` +(4) (0 1) +1 1 0 0 +1 0 1 0 +1 1 1 0 +1 0 0 1 +1 1 0 1 +1 0 1 1 +1 1 1 1 +``` + +`$cr` is the same cube, but we have reduced the lattice. (The first line is a *sparse representation* of a vector: it has length 4, and the only non-zero entry is at position 0 and is 1 (note that indexes start at 0)). + +## Toric Varieties + +`polymake` has only few builtin functions to compute properties of the variety associated to a fan or lattice polytope. There are two extensions available that add more properties, both currently at an early stage: + +* [Toric Varieties and Singular interface](https://github.com/lkastner) by Lars Kastner/Benjamin Lorenz + +* [ToricVarieties-v0.3](http://www.mathematik.tu-darmstadt.de/~paffenholz/software.html) by Andreas Paffenholz. Defines a new property for toric varieties associated to a fan and divisors on that variety. + +Here we will do some computations that do not require one of the extensions. We start by defining a fan. We'll make our live easy and take the normal fan of our cube: + + + + +```perl +application "fan"; +``` + +```perl +$f = normal_fan($p); +print $f->SMOOTH_FAN; +``` +Output: +``` +true +``` + +With the last line we have verified that our fan defines a smooth toric variety. Note that switching the application is not strictly necessary, you can also prepend calls to functions and constructors with `fan::`. The fan object `$f` itself knows its type, and chooses available properties based on this. Any smooth variety is Gorenstein, so we expect the following: + + + + +```perl +print $f->GORENSTEIN; +``` +Output: +``` +true +``` + +Similarly, we could check for Q-Gorensteinness with `Q_GORENSTEIN`. It is also a complete fan: + + + + +```perl +print $f->COMPLETE; +``` +Output: +``` +true +``` + +but currently there is little support to detect completeness in `polymake`. In our case it was already decided during construction, normal fans are complete. You can also check standard features of fans, like their rays. Let us do this for the normal fan of our other example: + + + + +```perl +$g=normal_fan($q); +print $g->RAYS; +``` +Output: +``` +-1 0 1/4 +0 -1 1/4 +1 0 0 +1 1 -1/4 +0 1 0 +0 0 -1 +0 -1 0 +-1 0 0 +``` + +This is not what we wanted. We would like to see the minimal lattice generators of the rays. We can fix this using + + + + +```perl +print primitive($g->RAYS); +``` +Output: +``` +-4 0 1 +0 -4 1 +1 0 0 +4 4 -1 +0 1 0 +0 0 -1 +0 -1 0 +-1 0 0 +``` + +Note that the function `primitive` returns a copy of the argument, the RAYS as stored in the fan are unchanged. So you have to apply this function each time you need the primitive generators, or you store them in a new variable. The fan $g$ is not smooth, but still Gorenstein: + + + + +```perl +print $g->SMOOTH_FAN; +``` +Output: +``` +false +``` + +```perl +print $g->GORENSTEIN; +``` +Output: +``` +true +``` + +You can also access the maximal cones of the fan via + + + + +```perl +print $g->MAXIMAL_CONES; +``` +Output: +``` +{0 1 6 7} +{0 1 2 4} +{0 4 7} +{1 2 6} +{2 3 4} +{5 6 7} +{3 4 5 7} +{2 3 5 6} +``` + +The indices in these list refer to the list of rays. Sometimes you might be interested in the walls, i.e. the codimension 2 faces of the fan. Here is one way to get them + + + + +```perl +print rows_numbered($g->HASSE_DIAGRAM->FACES); +``` +Output: +``` +0:-1 +1:0 1 6 7 +2:0 1 2 4 +3:0 4 7 +4:1 2 6 +5:2 3 4 +6:5 6 7 +7:3 4 5 7 +8:2 3 5 6 +9:0 1 +10:0 7 +11:1 6 +12:6 7 +13:0 4 +14:1 2 +15:2 4 +16:4 7 +17:2 6 +18:3 4 +19:2 3 +20:5 7 +21:5 6 +22:3 5 +23:0 +24:1 +25:7 +26:6 +27:4 +28:2 +29:3 +30:5 +31: +``` + +```perl +print $g->HASSE_DIAGRAM->nodes_of_dim($g->DIM-2); +``` +Output: +``` +{23 24 25 26 27 28 29 30} +``` + +where the list of numbers given by the latter are the indices of the codimension 2 faces in the list of all faces given before. There is a more concise way to list those, using some simple perl programming: + + + + +```perl +print map($g->HASSE_DIAGRAM->FACES->[$_], @{$g->HASSE_DIAGRAM->nodes_of_dim($g->DIM-2)}); +``` +Output: +``` +{0}{1}{7}{6}{4}{2}{3}{5} +``` + + + +## Visualization + +If the lattice polytope lives in R^2 or R^3, then we can visualize the polytope together with its lattice points. + + + +```perl +$p->VISUAL->LATTICE_COLORED; +``` + +The command `LATTICE_COLORED` sorted the lattice points into three classes before visualization: lattice points in the interior of the polytope, lattice points on the boundary, and vertices that are not in the lattice. These classes are then visualized with different colors (where we only see two in the above picture, as all vertices of the cube are in the lattice). If you don't need this distinction, `VISUAL->LATTICE` avoids the additional computations. + +## External Packages + +`polymake` can use `4ti2` and `lattE` via a file based interface and `libnormaliz >= 3.1.0` as library, (the file based interface to `normaliz` has been discontinued) for lattice computations and prints all available packages during startup. To tell `polymake` about a newly installed program run `polymake --reconfigure` or issue the command `reconfigure` during the interactive session. polymake may ask you to confirm the paths to the binaries. + + + Application polytope uses following third-party software (for details: help 'credits';) + 4ti2, cddlib, latte, libnormaliz, lrslib, nauty + + +The output at this position depends on the software available on your computer. To see each call to an external program you can set the variable `$Verbose::external=1;`. If you just want to see the credit message instead of the program call, set `$Verbose::credits=2` instead. If this is 1, then a credit is shown when a package is used for the first time, if 0, then all credits are suppressed (but you can find them in data files afterwards). + + + +```perl +$Verbose::external=1; +``` + +```perl +print $p->EHRHART_POLYNOMIAL; +``` +Output: +``` +8*x^3 + 12*x^2 + 6*x + 1 +``` + + +You can ask `polymake` to prefer one package over another by setting `prefer "program";` where program is one of `_4ti2`, `latte` and `normaliz2`. Of course, the corresponding package needs to be installed on your computer. + + +To prefer one program only for some computations you may append one of .integer_points, .hilbert, .ehrhartpoly for rules computing N_LATTICE_POINTS, LATTICE_POINTS, HILBERT_BASIS or EHRHART_POLYNOMIAL. (Or `prefer_now` just for the next computation) + + + + +```perl +print cube(2)->N_LATTICE_POINTS; +``` +Output: +``` +9 +``` + +```perl +prefer_now "libnormaliz"; +print cube(2)->N_LATTICE_POINTS; +``` +Output: +``` +9 +``` + +```perl +print cube(2)->EHRHART_POLYNOMIAL; +``` +Output: +``` +4*x^2 + 4*x + 1 +``` + +# Scripting + +From the technical point of view, there is no difference between +commands you enter in the interactive session and the scripts: in both +may any valid perl expression is accepted. The difference lies more in +the psychology: while for simple interactive commands practically no +knowledge in programming is needed, the scripting requires certain +profoundness in the perl language. + +But please don't be scared: even with minimal programming skills you can +save a lot of time and typing. The very first scripting exercise can +just consist of copying some lines from the interactive history buffer +(available by invoking `history;` command or directly from the file +`~/.polymake/history`) into a separate script file. As you better get +acquainted with perl and your programming experience grows, you'll be +able to realize more and more complex ideas. + +This page is not aimed, however, as an introduction in the perl +language. There is a lot of excellent literature available on this +topic, and even the man pages, otherwise notorious for their +ineligibility for novices, are very instructive and rich in explanatory +examples. Here you'll rather found details which are special to the +polymake's “dialect” of perl. + +## Calling + +A script can be called from the interactive polymake shell or from other +scripts via the special function `script`: + +``` code +script("scriptfile", arg1, ...); +``` + +As arguments any valid perl expressions may be passed. Alternatively, a +script may be executed directly from the UNIX command line: + +``` code +polymake --script scriptfile ARG1 ARG2 +``` + +Here you can only pass strings (like file names) or numeric constants as +arguments. Besides this restriction, you should keep in mind that if you +execute a script in this fashion, the readline library isn't loaded at +all, thus you won't be able to take any interactive actions like +importing extensions or reconfiguring some rules. Normally you will +hardly ever do it in your scripts, but should you need some interaction +in some exotic case, just change the option from `--script` to +`--iscript` . + +## Structure + +A script can contain pretty anything allowed by perl syntax rules. +However, to get access to polymake classes and functions, it needs a +preamble: + +``` code +use application "NAME"; +``` + +It sets a default application for the rest of the enclosing lexical +context (that is, normally, up to the next `use application` statement +or the end of the script file, but may also be just the enclosing +block). The notion of the default application has exactly the same +meaning as the [current +application](//polymake.org/doku.php/shell#switching_applications "shell") +for the interactive shell: Functions and class names defined in or +imported into the default application may be used without qualification, +while names from other applications must be prefixed by the application +name. + +The script code is compiled in the package `Polymake::User`, the same as +the interactive shell expressions are evaluated in. Thus the scripts can +access non-local variables introduced in the shell and vice versa, +having run the script once, you can use the variables and subroutines +defined in the script. If you want to define additional packages, please +define them as subpackages of `Polymake::User` or completely outside +`Polymake::`, to prevent accidental clashes with polymake internal +classes. + +The script may define subroutines and/or contain file-level code. The +latter is assembled together to a anonymous subroutine which is executed +each time you call the `script` function; its return value is the last +expression executed in the file-level code (or in a `return` statement, +if any). The arguments are passed in the global array `@ARGV`, not in +`@_` as for usual subroutines. If you intend to use your script in both +interactive and batch mode, you might want to build in some flexible +recognition of argument types, for example, allowing for both ready +objects and filenames to be passed: + +``` code + my $p=shift @ARGV; + $p=load($p) unless is_object($p); +``` + +Since the script code may be repeatedly executed arbitrarily many times, +you should put a special attention to variables requiring one-time +initialization. Such initializations should be either put in a `BEGIN` +block or guarded by `||=` or `//=` operators. Also please note that if +you introduce `my` variables on a file level and define other +subroutines in the script which refer to these variables, the +subroutines capture the values assigned during the first execution of +the script. Even if your script changes the values of these `my` +variables during each execution, the captured values in the subroutines +will remain unaffected. (It'll be of no surprise for seasoned perl +hackers familiar with the notion of *closures*). + +You can modify the script file in a text editor without leaving the +polymake session. The `script` function stores the timestamps of all +executed script files, so the changes will be detected by the next call +to `script` and the script file will be reloaded automatically. + +## Location + +Scripts can be kept in arbitrary folders. Unless the script you want to +execute resides in the current directory, you must specify its full path +in the `script` command. TAB completion assists you at this. There are, +however, special locations, where the scripts are found just by name. +Moreover, some locations impose special semantics on the scripts. + +Neutral scripts, that is, those capable of working with arbitrary +applications, and scripts explicitly switching the applications, can be +kept at the following places: + +- `$InstallTop/scripts` – standard neutral scripts shipped with polymake + +- `@lookup_scripts` – additional directories of your choice containing + your private scripts. This list is a [custom + variable](//polymake.org/doku.php/user_guide/howto/shell_custom#custom_variables "user_guide:howto:shell_custom"). + +- `$Extension/scripts` – neutral scripts coming from an + [extension](//polymake.org/doku.php/user_guide/extend/extensions "user_guide:extend:extensions") + +Application-specific scripts are kept in the applications' subtrees: + +- `$InstallTop/apps/APPNAME/scripts` – standard scripts shipped with + polymake + +- ` $Extension/apps/APPNAME/scripts` – scripts coming from an extension + +These scripts don't need the preamble `use application`, it is +automatically imposed. An application-specific script can be executed +with the `script` command if its application is the current one or is +imported by the current application. + +Your collection of scripts will probably grow over the time, some +scripts sharing common code parts. The common code is usually extracted +in separate `.pl` or `.pm` files included with `require` statement. The +lookup rules for these files is a bit different: the directories to be +searched have to be inserted into the global array `@INC`. The +appropriate `push` or `unshift` statements can be placed in your +personal startup script `~/.polymake/init.pl`. We recommend, however, to +create a private extension and store the scripts and the included files +in subdirectories `scripts` and `perllib` respectively. In this setting +you don't have to manipulate any lookup list. + diff --git a/apn/lean/docs/prover9/LICENSE b/apn/lean/docs/prover9/LICENSE new file mode 100644 index 00000000..d511905c --- /dev/null +++ b/apn/lean/docs/prover9/LICENSE @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/apn/lean/docs/prover9/prover9-manual.md b/apn/lean/docs/prover9/prover9-manual.md new file mode 100644 index 00000000..932be9e3 --- /dev/null +++ b/apn/lean/docs/prover9/prover9-manual.md @@ -0,0 +1,3218 @@ + + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Introduction + +[Prover9](http://www.cs.unm.edu/~mccune/prover9/) is a +resolution/paramodulation automated theorem prover for first-order and +equational logic. Prover9 is a successor of the +[Otter](http://www.cs.unm.edu/~mccune/otter/) Prover +\[[McCune-Otter33](references.html#McCune-Otter33)\]. + +## Getting Started + +Prover9 has a fully [automatic mode](auto.html) in which the user simply +gives it formulas representing the problem. See the Section [Clauses and +Formulas](syntax.html). + +An good way to learn about Prover9 is to browse and study the [example +input and output +files](http://www.cs.unm.edu/~mccune/prover9/examples/). *Users are +encouraged to contribute examples from their own work with Prover9 (and +Mace4).* + +## Related Programs + +Several programs come bundled with Prover9. The most important is +[Mace4](mace4.html), which looks for finite models and counterexamples. +Mace4 can help avoid wasting time searching for a proof with Prover9 by +first finding a counterexample or by first helping to debug logical +specifications. + +Another useful program is [Prooftrans](prooftrans.html), which can +transform proofs found by Prover9 in various ways, including producing +more detailed proofs, simplifying the justifications, renumbering the +steps, producing proofs in XML, and producing proofs for input to other +programs. + +## Terms of Use + +Prover9, Mace4, related programs, and the LADR libraries (with which +they were all constructed) are distributed under the terms of the [**GNU +General Public License (v2)**](http://www.gnu.org/copyleft/gpl.html). + +## Other Theorem Provers + +- [E](http://www.eprover.org) is a very good all-around prover. +- [Waldmeister](http://www.mpi-sb.mpg.de/~hillen/waldmeister/) is a fast + prover for equational logic. +- [Vampire](http://en.wikipedia.org/wiki/Vampire_theorem_prover) has + lately been winning the MIX category of + [CASC](http://www.cs.miami.edu/~tptp/CASC/). +- [Paradox](http://www.cs.chalmers.se/~koen/paradox/) is an excellent + program for finding finite models and counterexamples. +- See the [CASC Website](http://www.cs.miami.edu/~tptp/CASC/) for + information on lots of other good provers. + +## Format Conventions for this Manual + +Many parts of this manual are displayed in boxes with different +background colors. + +A display like the following indicates part of an input or output file. + +``` my_file +formulas(sos). + all x all y (subset(x,y) <-> (all z (member(z,x) -> member(z,y)))). +end_of_list. + +formulas(goals). + all x all y all z (subset(x,y) & subset(y,z) -> subset(x,z)). +end_of_list. +``` + +A display like the following indicates a job that is run on a command +line, for example, a command to run a Prover9 job. + +``` my_job +prover9 -f subset_trans.in > subset_trans.out +``` + +A display like the following indicates some output that appears on the +computer screen, for example, a message from Prover9. + +``` my_screen +-------- Proof 1 -------- +THEOREM PROVED +------ process 3666 exit (max_proofs) ------ +``` + +Displays like the following contain algorithms. + +``` my_code +Simplify clause (c): + demodulate c + merge identical literals +``` + +A display like the following notes an important difference between +Prover9 and Otter. + +> Prover9's automatic mode is set by default. Otter's automatic mode +> must be explicitly set. + +------------------------------------------------------------------------ + +Next Section: [Installation](install.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Running Prover9 + +The standard way of running Prover9 is to (1) prepare an input file +containing the logical specification of a conjecture and the search +parameters, (2) issue a command that runs Prover9 on the input file and +produces an output file, (3) look at the output, and (4) maybe run +Prover9 again with different search parameters. + +A [graphical user interface (GUI) for +Prover9](http://www.cs.unm.edu/~mccune/prover9/gui/) is under +development, but it is not described in this manual. Nearly all of the +information in this manual applies also when using the GUI. + +## An Input File + +Here is an input file; assume it is named `subset_trans.in`. +(Use a plain text editor, not a word processor, to create input files.) + +``` my_file +formulas(sos). + all x all y (subset(x,y) <-> (all z (member(z,x) -> member(z,y)))). +end_of_list. + +formulas(goals). + all x all y all z (subset(x,y) & subset(y,z) -> subset(x,z)). +end_of_list. +``` + +## A Basic Prover9 Command + +Here is a command to run Prover9 on the preceding file and send the +output to a file called `subset_trans.out`. + +``` my_job +prover9 -f subset_trans.in > subset_trans.out +``` + +When you run the preceding command, a message like the following should +appear immediately on your screen. + +``` my_screen +-------- Proof 1 -------- +THEOREM PROVED +------ process 3666 exit (max_proofs) ------ +``` + +The output file [subset_trans.out](subset_trans.out) should contain the +proof (and a lot of other information about the job). + +## Taking Input from Standard Input + +Prover9 jobs can be run in a slightly different way, taking input from +"standard input" instead of a named file, as follows. + +``` my_job +prover9 < subset_trans.in > subset_trans.out2 +``` + +The disadvantage of using this method is that the name of the input file +is not given in the output file. + +## More Than One Input File + +The input can occur in more than one file: + +``` my_job +prover9 -f subset.in trans.in > subset_trans.out3 +``` + +All arguments after the "`-f`" are taken as input filenames, and there +can be as many as you like. When multiple filnames are given on the +command line, a list of objects (clauses, formulas, or terms) cannot be +split across more than one file. + +## Time Limit on the Command Line + +Prover9 also accepts a time limit, in seconds, on the command line. The +following command limits the job to about 10 seconds. + +``` my_job +prover9 -t 10 -f subset_trans.in > subset_trans.out4 +``` + +If "`-t`" and "`-f`" are both in the command, the "`-t`" must occur +first. + +## Getting Statistics During the Search + +*This section applies to Unix-like systems only.* + +If a Prover9 process is running in the background, one can tell it to +send search statistics (without killing the job) to the output file +sending a "USR1" signal to the process. For example, + +``` my_job +% prover9 -f p3a.in > p3a.outb & + [1] 31613 +% kill -USR1 31613 + A report (17.75 seconds) has been sent to the output. +``` + +## Calling Prover9 From Another Program + +If Prover9 is called from another program (e.g., a shell script, a Perl +script, or a Python script), Prover9's exit codes can tell the other +program the reason Prover9 terminates. The following table shows the +exit codes. + +Exit Code + +Reason for Termination + +0 (MAX_PROOFS) + +The specified number of proofs +([**`max_proofs`**](limits.html#max_proofs)) was found. + +1 (FATAL) + +A fatal error occurred (user's syntax error or Prover9's bug). + +2 (SOS_EMPTY) + +Prover9 ran out of things to do (sos list exhausted). + +3 (MAX_MEGS) + +The [**`max_megs`**](limits.html#max_megs) (memory limit) parameter was +exceeded. + +4 (MAX_SECONDS) + +The [**`max_seconds`**](limits.html#max_seconds) parameter was exceeded. + +5 (MAX_GIVEN) + +The [**`max_given`**](limits.html#max_given) parameter was exceeded. + +6 (MAX_KEPT) + +The [**`max_kept`**](limits.html#max_kept) parameter was exceeded. + +7 (ACTION) + +A Prover9 [action](actions.html) terminated the search. + +101 (SIGINT) + +Prover9 received an interrupt signal. + +102 (SIGSEGV) + +Prover9 crashed, most probably due to a bug. + +The calling program will probably want to look in Prover9's output, for +example, to extract a proof. See the page on [Prover9 output +files](output.html). + +------------------------------------------------------------------------ + +Next Section: [Input Files](input.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Prover9 Input Files + +Prover9 takes its input from one or more (usually one) files. If there +is more than one input file, lists of objects (formulas, weighting +rules, etc.) cannot be split across more than one file. The page +[Running Prover9](running.html) shows how to specify the files in the +commands to run Prover9. + +## Comments and Whitespace + +There are two kinds of comment: + +- *Line comment*. If the first '`%`' (percent sign) on a line is not the + start of a block comment ('`%BEGIN`'), everything from that symbol + through the end of the line is ignored. +- *Block comment*. If the parser sees the string '`%BEGIN`', that is not + in a line comment, it will ignore everything up through the next + occurrence of '`END%`'. Line breaks are irrelevant. If there is no + '`END%`', the rest of the file is ignored, without causing an error. + +Comments are not echoed to the output file. Clauses can have [label +attributes](attributes.html) which can serve as different kind of +comment which *does* appear in the output file. + +Whitespace (spaces, newlines, tabs, etc.) is optional in most places. +The important exception is that whitespace is required around some +operations in clauses and formulas (see the page [Clauses and +Formulas](syntax.html)). + +## A Simple Example + +The most basic kind of input file consists of list of +[clauses](glossary.html#clause) named "`sos`" representing the negation +of the conjecture, as in the following example. + +``` my_file +formulas(sos). % clauses to be placed in the sos list + -man(x) | mortal(x). + man(george). + -mortal(george). +end_of_list. +``` + +Prover9 will take the clauses, use its automatic mode to decide on the +inference rules, and then search for a refutation. + +The preceding example can also be stated in a more natural way by using +a non-clausal formula for the man-implies-mortal rule and the [`goals` +list](goals.html) for the conclusion, as follows. + +``` my_file +formulas(assumptions). % synonym for formulas(sos). + man(x) -> mortal(x). % open formula with free variable x + man(george). +end_of_list. + +formulas(goals). % to be negated and placed in the sos list + mortal(george). +end_of_list. +``` + +Prover9 will transform the formulas in this input to the same clauses as +in the basic input above before starting the search for a refutation. + +> In Otter and in earlier versions of Prover9, "clauses" and "formulas" +> were distinct types of object, and formulas could not have free +> variables. Now, clauses are a subset of formulas, and Prover9 decides +> which formulas are non-clausal and takes the appropriate actions to +> transform them to clauses. + +## Types of Input + +Prover9 input consists of lists of objects (formulas or terms) and +commands. + +### Lists of Objects + +Lists of objects start with a type (`formulas` or `terms`) and name +(`sos`, `goals`, `weights`, etc.), and end with `end_of_list`. The +following display show an example of each type of accepted list, with +one object in each list. + +``` my_file +formulas(sos). p(x). end_of_list. % the primary input list +formulas(assumptions). p(x). end_of_list. % synonym for formulas(sos) +formulas(goals). p(x). end_of_list. % some restrictions (see Goals) +formulas(usable). p(x). end_of_list. % seldom used +formulas(demodulators). f(x)=x. end_of_list. % seldom used, must be equalities +formulas(hints). p(x). end_of_list. % should be used more often (see Hints) + +list(weights). weight(a) = 10. end_of_list. % see Weighting +list(kbo_weights). a = 3. end_of_list. % see Term Ordering +list(actions). given = 100 -> set(print_kept). end_of_list. % see Actions +list(interpretations). interpretation(2,[],[relation(p,[1])]). end_of_list. % see Semantics +``` + +If the input contains more than one list of a particular type/name, the +lists are simply concatenated by Prover9 as they are read. + +### Commands + +Eleven types of command are accepted. Here is an example of each. + +``` my_file +op(400, infix_right, ["+", "--"]). % declare parse precedence and type (see Clauses and Formulas) + +redeclare(negation, "~"]). % change the negation symbol (see Clauses and Formulas) + +set(print_kept). % set a flag + +clear(auto_inference). % clear a flag + +assign(max_weight, 40). % integer parameter + +assign(stats, some). % string parameter + +assoc_comm(*). % not currently used for Prover9 + +commutative(g). % not currently used for Prover9 + +predicate_order([=,<=,P,Q). % predicate symbol precedence (see Term Ordering) + +function_order([0,1,a,b,f,g,*,+]). % function symbol precedence (see Term Ordering) + +lex([0,1,a,b,f,g,*,+]). % synonym for "function_order" + +skolem([a,b,f,g]). % declare symbols to be Skolem functions (rarely used) +``` + +## Order of Commands and Lists of Objects + +For the most part, the order of things in the input file(s) is +irrelevant. For example, commands can usually be mixed with lists of +objects. The situations in which order matters are listed here. + +- The `op(precedence, type, symbols)` commands must occur before any + clauses or formulas that contain the affected symbols. +- Some of the flags and parameters alter other flags and parameters. The + alterations can be undone by placing the appropriate command after the + command that alters. The output file clearly shows what happens in + these cases. + +Note that changing the order of clauses or formulas within a list, +changing the order of literals in a clause, or changing the order of +subformulas in a formula can change the search, occasionally in +substantial ways. + +## Conditional Inclusion + +Many input files can be used for multiple programs (e.g., Prover9 and +Mace4). The following construct says to include the enclosed input for +the given program only. + +``` my_file +if(program-name). + ... conditionally-included input ... +end_if. +``` + +For example, to specify that Mace4 and Prover9 have different time +limits, one can write + +``` my_file +if(Mace4). + assign(max_seconds, 30). +end_if. + +if(Prover9). + assign(max_seconds, 3600). +end_if. +``` + +The conditional-inclusion construct cannot occur within a list of +objects (formulas, weighting rules, etc.). + +------------------------------------------------------------------------ + +Next Section: [Clauses & Formulas](syntax.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Clauses and Formulas + +The [Glossary Page](glossary.html) contains definitions of +[term](glossary.html#term), [atomic +formula](glossary.html#atomic%20formula), +[literal](glossary.html#literal), [clause](glossary.html#clause), and +[formula](glossary.html#formula) from a logical point of view. This page +contains descriptions of how those kinds of things are parsed and +printed, and we refer to them collectively as *objects*. + +> In Otter and in earlier versions of Prover9, "clauses" and "formulas" +> were distinct types of object, and "formulas" could not have free +> variables. Now, clauses are a subset of formulas. + +Here are the important points about clauses and formulas. + +- Clauses are a subset of formulas. All input formulas, including + clauses, appear in a list headed by `formulas(`*`list_name`*`)`. +- There is a rule for distinguishing variables from constants, because + clauses and other formulas can have free variables (variables not + bound by quantifiers). The default rule is that variables start with + (lower case) `u` through `z`. For example, in the formula `P(a,x)`, + the term `a` is a constant, and `x` is a variable. (See also the flag + [**`prolog_style_variables`**](syntax.html#prolog_style_variables).) +- Free variables in clauses and formulas are assumed to be universally + quantified at the outermost level. +- Prover9's inference rules operate on clauses. If non-clausal formulas + are input, Prover9 immediately translates them clauses by + [NNF](glossary.html#NNF), + [Skolemization](glossary.html#skolemization), and + [CNF](glossary.html#CNF) conversions. + +## Parsing and Printing Objects + +The *prefix standard form* of an object with an n-ary symbol, say `f`, +at the root is + +``` my_file +f( argument_1, ..., argument_n ) +``` + +Whitespace (spaces, tabs, newline, etc.) is accepted anywhere except +within symbols. + +Prover9 will accept any term or formula written prefix standard form. +However formulas and many terms can be written in more convenient ways, +for example, "`a=b | a!=c'`" instead of "`|(=(a,b),-(=(a,'(c))))`". + +Prover9 uses a general mechanism in which binary and unary symbols can +have special parsing properties such as "infix", +"infix-right-associated", "postfix". In addition, each of those symbols +has a precedence so that many parentheses can be omitted. (The mechanism +is similar to those used by most Prolog systems.) + +Many symbols have built-in parsing properties (see the [table +below](#built_in)), and the user can declare parsing properties for +other symbols with the "op" command. + +Clauses and formulas make extensive use of the built-in parsing +properties for the equality relation and the logic connectives. Instead +of first presenting the general mechanism, we will present the syntax +for formulas under the assumption of the built-in parsing properties. +The general mechanism is described below in the section [Infix, Prefix, +and Postfix Declarations](#declarations). + +### Symbols + +Symbols include variables, constants, function symbols, predicate +symbols, logic connectives. Symbols do not include parentheses or +commas. + +Prover9 recognizes several kinds of symbol. + +- An *ordinary symbol* is a (maximal) string made from the characters + `a`-`z`, `A`-`Z`, `0`-`9`, `$`, and `_`. +- A *special symbol* is a (maximal) string made from the *special + characters*: `` {+-*/\^<>=`~?@&|!#';} ``. +- A *quoted symbol* is any string enclosed in double quotes. +- The *empty list symbol* is `[]`. This is a special case. + +The reason for separating ordinary and special symbols is so that +strings like `a+b`; that is, `+(a,b)`, can be written without any +whitespace around the `+`. + +A symbol cannot have both ordinary and special characters, for example +`R+` (unless it is a quoted symbol). + +Objects (terms or formulas) are constructed from symbols, parentheses, +and commas. + +### Overloaded Symbols + +In most cases, symbol overloading is not allowed. For example a symbol +cannot be both a function symbol and a predicate symbol, or both a +constant and a binary function symbol. There are a few exceptions. + +- The logic connectives can also be used as function or predicate + symbols of the same arity. For example, `-` is typically used as unary + arithmetic minus well as for logical negation. + +> Prover9 is much more strict about overloading symbols than Otter is. + +### Symbols With Meaning + +Several symbols have built-in meaning. These are the equality symbols +(`=`, `!=`) and logic connectives (`-`, `|`, `&`, `->`, `<-`, `<->`, +`all`, `exists`). These symbols can be changed as described in the +section [Redeclaring Built-in Symbols](#redeclare). (Parentheses, comma, +period, and the list construction symbols cannot be redeclared.) + +Terms + +Any term can be written in prefix standard form, for example, +`f(g(x),y)` and `*('(x),y)`. If symbols in the term have +parsing/printing properties (either [built-in](#built_in)) or declared +with the `op` command), the term can be written in infix/prefix/postfix +form with assumed precedence, for example, `x'*y`, which represents +`*('(x),y)` under the built-in parsing/printing properties. + +A list notation similar to Prolog's can be used to write terms that +represent lists. Note that the "cons" operator is "`:`", instead of +"`|`" as in Prolog. + +Term + +Standard Prefix Form + +What it Is + +`[]` + +`$nil` + +the empty list + +`[a,b,c]` + +`$cons(a,$cons(b,$cons(c,$nil)))` + +list of three objects + +`[a:b]` + +`$cons(a,b)` + +first, rest + +`[a,b:c]` + +`$cons(a,$cons(b,c))` + +first, second, rest + +Lists are frequently used in Prover9 commands such as the +[`function_order`](input.html#lists) command, and they are sometimes +also used in clauses and formulas. + +### Atomic Formulas + +Equality is a built-in special case. The binary predicate symbol `=` is +usually written as an infix relation. The binary symbol `!=` is an +abbreviation for "not equal"; that is, the formula `a!=b` stands for +`-(a=b)`, or more precisely, `-(=(a,b))`. From the semantics point of +view, the binary predicate symbol `=` is the one and only equality +symbol for the inference rules that use equality. + +### Clauses + +The disjunction (OR) symbol is `|`, and the negation (NOT) symbol is +`-`. The disjunction symbol has higher precedence than the equality +symbol, so equations in clauses do not need parentheses. Every clause +ends with a period. Examples of clauses follow (Prover9 adds some extra +space when printing clauses). + +``` my_file +formulas(sos). + p|-q|r. + a=b|c!=d. + f(x)!=f(y)|x=y. +end_of_list. +``` + +### Formulas + +Meaning + +Connective + +Example + +negation + +`-` + +`(-p)` + +disjunction + +`|` + +`(p | q | r)` + +conjunction + +`&` + +`(p & q & r)` + +implication + +`->` + +`(p -> q)` + +backward implication + +`<-` + +`(p <- q)` + +equivalence + +`<->` + +`(p <-> q)` + +universal quantification + +`all` + +`(all x all y p(x,y))` + +existential quantification + +`exists` + +`(exists x exists y p(x,y))` + +When writing formulas, the [built-in parsing declarations](#built_in) +allow many parentheses to be omitted. For example, the following two +formulas are really the same formula. + +``` my_file +formulas(sos). + all x all y (p <-> -q | r & -s) . +(all x (all y (p <-> ((-q) | (r & (-s)))))). +end_of_list. +``` + +> For Prover9 formulas, each quantified variable must have its own +> quantifier; Otter allows quantifiers to be omitted in a sequence of +> quantified variables with the same quantifier. For example, Otter +> allows `(all x y z p(x,y,z))`, and Prover9 requires +> `(all x all y all z p(x,y,z))`. + +Infix, Prefix, and Postfix Declarations + +Several symbols are understood by Prover9 as having special parsing +properties that determine how terms involving those symbols can be +arranged. In addition, the user can declare additional symbols to have +special parsing properties. + +### Parsing Declarations + +The "op" command is used to declare parse types and precedences. + +``` my_file +op( precedence, type, symbols(s) ). % declare parse type and precedence +``` + +- 1 ≤ *`precedence`* ≤ 998. +- *`type`* is one of { + `infix, infix_left, infix_right, prefix, prefix_paren, postfix, postfix_paren, ordinary` + }. +- *`symbol(s)`* is either a symbol or a list of symbols. Each + multi-character special symbol must be enclosed in double quotes. + +> Prover9 does not allow different symbol types with the same +> precedence, for example, +> +> ``` my_file +> op(325, postfix, '). +> op(325, prefix, ~). +> ``` +> +> This restriction prevents ambiguous strings such as `~x'`. + +The following table shows an example of each type of parsing property +(and ignores precedence). + +Type + +Example + +Standard Prefix + +Comment + +`infix` + +`a*(b*c) ` + +`*(a,*(b,c))` + +like Prolog's `xfx` + +`infix_left` + +`a*b*c ` + +`*(*(a,b),c)` + +like Prolog's `yfx` + +`infix_right` + +`a*b*c ` + +`*(a,*(b,c))` + +like Prolog's `xfy` + +`prefix` + +`--p ` + +`-(-(p)) ` + +like Prolog's `fy` + +`prefix_paren` + +`-(-p) ` + +`-(-(p)) ` + +like Prolog's `fx` + +`postfix` + +`a'' ` + +`'('(a)) ` + +like Prolog's `yf` + +`postfix_paren` + +`(a')' ` + +`'('(a)) ` + +like Prolog's `xf` + +`ordinary` + +`*(a,b) ` + +`*(a,b) ` + +takes away parsing properties + +Higher precedence means closer to the root of the object, and lower +precedence means the the symbol binds more closely. For example, assume +that the following declarations are in effect. + +``` my_file +op(790, infix_right, "|" ). % disjunction in formulas or clauses +op(780, infix_right, "&" ). % conjunction in formulas +``` + +Then the string `a & b | c` is an abbreviation for `(a & b) | c`. + +The built-in parsing declarations are shown in the following box. The +ones with comments have built-in meanings; the others are for general +use as function or predicate symbols. + +``` my_file +op(810, infix_right, "#" ). % for attaching attributes to clauses + +op(800, infix, "<->" ). % equivalence in formulas +op(800, infix, "->" ). % implication in formulas +op(800, infix, "<-" ). % backward implication in formulas +op(790, infix_right, "|" ). % disjunction in formulas or clauses +op(780, infix_right, "&" ). % conjunction in formulas + +% Quantifiers (a special case) have precedence 750. + +op(700, infix, "=" ). % equal in atomic formulas +op(700, infix, "!=" ). % not equal in atomic formulas +op(700, infix, "==" ). +op(700, infix, "<" ). +op(700, infix, "<=" ). +op(700, infix, ">" ). +op(700, infix, ">=" ). + +op(500, infix, "+" ). +op(500, infix, "*" ). +op(500, infix, "@" ). +op(500, infix, "/" ). +op(500, infix, "\" ). +op(500, infix, "^" ). +op(500, infix, "v" ). + +op(350, prefix, "-" ). % logical negation in formulas or clauses +op(300, postfix, "'" ). +``` + +The built-in parsing declarations can be overridden with ordinary "op" +commands. Be careful, however, when overriding parsing declarations for +symbols with built-in meanings. For example, say you wish to use "#" as +an infix function symbol and give the following the declaration. + +``` my_file +op(500, infix, "#"). +``` + +Then clauses with attributes might have be written with more +parentheses, for example, as + +``` my_file +(p(a) | q(a)) # (label(a) # label(b)). +``` + +If you wish to use one of the symbols with built-in parsing declarations +as an ordinary prefix symbol, you can undo the declaration by giving an +"op" command with type "ordinary". The following example clears the +parse types for two symbols. + +``` my_file +op(ordinary, ["*","+"]). % there is no precedence argument for type "ordinary" +``` + +Finally, the following example shows that parsing declarations can be +changed anywhere in the input, with immediate effect. This can be useful +for example, if lists of clauses come from different sources. + +``` my_file +op(400,infix_left,"*"). % assume left association for following clauses + +formulas(sos). + P(a * b * c). +end_of_list. + +op(400,infix_right,"*"). % assume right association for following clauses + +formulas(sos). + Q(d * e * f). +end_of_list. + +op(400,infix,"*"). % from here on, include all parentheses (input and output) +``` + +An excerpt from the output of the preceding example shows how the +clauses are printed after the last "op" command. + +``` my_file +formulas(sos). +P((a * b) * c). [assumption]. +Q(d * (e * f)). [assumption]. +end_of_list. +``` + +## Prolog-Style Variables + +``` my_option +set(prolog_style_variables). +clear(prolog_style_variables). % default clear +``` + +> A rule is needed for distinguishing variables from constants in +> clauses and formulas with free variables. If this flag is clear, +> variables in clauses start with (lower case) 'u' through 'z'. If this +> flag is set, variables in clauses start with (upper case) 'A' through +> 'Z'. +> +> Prover9 decides whether symbols are constants or variables after it +> has read all of its input, so the state of the flag +> [**`prolog_style_variables`**](syntax.html#prolog_style_variables) at +> the end of the input determines the rule that is used for *all* +> formulas. For example, in the following input, +> +> ``` my_file +> formulas(sos). +> p(x,A). +> end_of_list. +> +> set(prolog_style_variables). +> +> formulas(sos). +> q(y,B). +> end_of_list. +> ``` +> +> the term `x` is a constant, and `A` is a variable. + +Redeclaring Built-in Symbols + +NOTE: Keep in mind the difference between *semantic* properties of +symbols (e.g., logic connectives) and *parsing/printing* properties of +symbols (e.g., infix with high precedence). Those two kinds of property +are independent (by default, many symbols have both). + +Most of the symbols with built-in meaning can be changed to other +symbols. The symbols that can be changed are shown in the following +table. + +Operation + +Default Symbol + +true + +`$T` + +false + +`$F` + +negation + +`-` + +disjunction + +`|` + +conjunction + +`&` + +implication + +`->` + +backward_implication + +`<-` + +equivalence + +`<->` + +universal_quantification + +`all` + +existential_quantification + +`exists` + +equality + +`=` + +negated_equality + +`!=` + +attribute + +`#` + +To change the symbol associated with an operation, one uses the +following command. + +``` my_file +redeclare( operation, symbol ). % associate a different symbol with an operation +``` + +For example, the following command says that "`AND`" will be used for +conjunction. + +``` my_file +redeclare(conjunction, AND). % change the conjunction symbol to AND. +``` + +As with the "`op`" command, if the new symbol is a multicharacter +[special symbol](#special_symbol), it must be enclosed in double quotes, +as in the following example. + +``` my_file +redeclare(conjunction, "&&"). % change the conjunction symbol to &&. +``` + +When in doubt, quote the symbol, because unnecessary quotes are ignored +in the "`redeclare`" and "`op`" commands. + +### Parsing/Printing Properties and Redeclarations + +Many of the default symbols for the built-in operations have default +printing/parsing properties, for example, the default properties for +default conjunction symbol are + +``` my_file +op(780, infix_right, "&" ). % conjunction in formulas +``` + +When a redeclaration for such an operation occurs, the parsing/printing +properties are copied from the old symbol to the new symbol. For +example, when conjunction is changed to `AND`, the following is +*automatically* applied. + +``` my_file +op(780, infix_right, AND ). +``` + +If the user wishes some other printing/parsing properties for the new +symbol, the appropriate "`op`" command can be placed after the +"`redeclare`" command. + +### Redeclaration Example + +The following example shows redeclarations of many of the operations. + +``` my_job +prover9 -f redeclare.in > redeclare.out +``` + +### Location of Redeclare Commands + +Most of the operations can be redeclared repeatedly throughout the +input. The declarations in effect when a formula is read will be used, +ane the ones in effect at the end of the input will be used for all +subsequent output. + +*An exception*: If the operations "`equality`" or "`negated_equality`" +are redeclared, it must be done before any formulas containing those +symbols are read. + +------------------------------------------------------------------------ + +Next Section: [Auto Modes](auto.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Goals and Denials + +This section shows how the conclusion(s) of a conjecture can be stated +in positive form, how one can search for direct proofs as opposed to +bidirectional proofs, and how multiple conclusions are stated and +handled. + +Terminology + +- *Conclusion*: this term is used informally. +- *Goal*: this term refers to a conclusion stated in positive form. +- *Denial clause*: this term refers to a negative clause in a [Horn + set](glossary.html#horn), because such clauses usually correspond to + the negation of a conclusion. + +## Goals: Stating Conclusions in Positive Form + +> In Otter, the conclusions are always stated in negated form. + +Prover9 allows the user to state conclusions in positive form by using +the list `formulas(goals)`. However, Prover9 always works by refutation, +so the clauses or formulas in the `goals` lists are negated as described +below, and the results are appended to the `sos` clause list before the +search starts. In other words, goals are "syntactic sugar" for input, +and have nothing to do with the way Prover9 conducts its search for +refutations. + +When the conclusion is given in positive form, the user has no control +over the [Skolem](glossary.html#skolemization) symbols (if any) that +Prover9 introduces. If the user needs some control of the Skolem +symbols, for example, to insert them into the symbol precedence at a +particular spot, or to include them in the weighting function, the user +should do the Skolemizing and give the conclusion in negated form. + +If there is just one formula in `formulas(goals)`, the meaning is clear: +the formula is processed by first taking its universal closure, then +negating. The formula is then handled exactly as if it had been input in +`formulas(sos)`, that is, by Skolemizing and transforming to clauses. + +### Multiple Goals + +If there is more than one formula in `formulas(goals)`, the meaning is +not clear. Is the conclusion the disjunction of those formulas? Or the +conjunction? *The answer: disjunction*: if any goal is proved, the proof +is reported, printed, and counted. + +Multiple *complex* goals are not allowed, because the quantification of +free variables can be very confusing. Therefore Prover9 enforces the +following rule. + +> *If there is more than one formula in the goals list, each must be a +> positive universal conjunctive formula, that is a formula constructed +> from atomic formulas, universal quantification, and conjunction only.* + +To avoid this restriction, one can always write the conclusion clearly +as a single goal formula containing any of the logic connectives and +quantification. However, if the conjecture involves multiple complex +conclusions, we recommend, for search efficiency, separate Prover9 +searches. + +If there are multiple goals, each is processed separately by applying +universal closure, negation, and transformation to clauses. After this +processing, Prover9 forgets that there were multiple goals and simply +searches for refutations. + +When there are multiple goals, and when the user wishes to prove more +than one goal, the parameter [**`max_proofs`**](goals.html#max_proofs) +should be set to an appropriate value. (The flag +[**`auto_denials`**](goals.html#auto_denials) (default set) can do so +automatically.) + +## Multiple Proofs + +``` my_option +assign(max_proofs, n). % default n=1, range [-1 .. INT_MAX] +``` + +> This parameter tells Prover9 to stop searching when the *n*-th proof +> has been found. + +## Denials: Negative Clauses in Horn Sets + +Denial clauses (negative clauses in Horn sets) can be derived from +goals, or they can be input directly as negative clauses. + +### Multiple Proofs of the Same Conclusion + +``` my_option +set(reuse_denials). +clear(reuse_denials). % default clear +``` + +> If this flag is set, when a denial clause (a negative clause in a Horn +> set) is used in a proof, and when +> [**`max_proofs`**](goals.html#max_proofs) says to search for more +> proofs, subsequent proofs may be of the same conclusion. (Multiple +> proofs of the same conclusion may be useful when one is searching for +> *short* proofs.) +> +> If this flag is clear, then when a proof is found, the denial and all +> of its descendants are disabled so that they will not appear in +> subsequent proofs. +> +> This flag is independent of the flag +> [**`restrict_denials`**](goals.html#restrict_denials). + +### Auto_denials + +``` my_option +set(auto_denials). % default set +clear(auto_denials). +``` + +> If this flag is set (the default), negative clauses in [Horn +> sets](glossary.html#horn) receive some special initial processing. +> +> If a Horn set has more than one denial (negative) clause, we assume +> they correspond to separate conclusions, and the user wishes to have a +> separate proof of each conclusion. Therefore, if +> [**`max_proofs`**](goals.html#max_proofs) has not been changed from +> its default value of 1, we assign to +> [**`max_proofs`**](goals.html#max_proofs) the number of negative +> clauses. (Note that when +> [**`reuse_denials`**](goals.html#reuse_denials) is clear (the +> default), Prover9 prevents multiple proofs of the same conclusion.) +> +> Also, if a negative clause in a Horn set has label attribute but no +> answer attribute, the clause is given an answer attribute +> corresponding to the first label attribute. This saves the user from +> changing "label" to "answer" when moving formulas from the `sos` list +> to the `goals` list. + +### Forward or Direct Proofs + +The following flag restricts the use of negative clauses, with the aim +of finding proofs that are more direct; that is, proofs that go forward +from the hypotheses to the conclusion rather than proofs that reason +backward from the conclusion. + +Ordinarily, the term *denial* refers to a negative clause in a Horn set. +Here, we use it for any negative clause. Originally, the flag +[**`restrict_denials`**](goals.html#restrict_denials) applied only to +Horn sets, but we eliminated that restriction when we realized that it +can be useful for non-Horn sets. However, its use has been well analyzed +for non-Horn sets. + +``` my_option +set(restrict_denials). +clear(restrict_denials). % default clear +``` + +> If the flag is set, negative clauses (clauses in which all literals +> are negative) are referred to as *restricted denials* and are given +> special treatment. +> +> The inference rules (i.e., paramodulation and the resolution rules) +> will not be applied to restricted denials. However, restricted denials +> will be simplified by [back demodulation](glossary.html#demodulation) +> and [back unit deletion](glossary.html#unit-deletion). +> +> In addition, restricted denials will not be deleted if they are over +> the weight limit ([**`max_weight`**](process-inf.html#max_weight)). +> +> The effect of setting +> [**`restrict_denials`**](goals.html#restrict_denials) is that proofs +> will usually be more forward or direct. This option can speed up +> proofs, it can delay proofs, and it can block all proofs. + +## An Example + +The following example illustrates multiple goals (including a goal that +is a combination of other goals), +[**`auto_denials`**](goals.html#auto_denials), and +[**`restrict_denials`**](goals.html#restrict_denials). + +``` my_job +prover9 -f olsax.in > olsax.out +``` + +------------------------------------------------------------------------ + +Next Section: [Production Mode](production.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Prover9 Options + +There are three kinds of options: + +- *Flags* are Boolean-valued options which can be changed with the *set* + and *clear* commands, e.g., + `set(clocks)`. + `set(print_given)`. +- *Parms* are integer-valued options which can be changed with the + *assign* command, e.g., + `assign(max_weight, 30)`. +- *Stringparms* are string-valued options which can be changed with the + *assign* command, e.g., + `assign(order, kbo)`. + +## Option Dependencies + +Several of the flags and parameters cause other flags and parameters to +be changed. In some cases, that is the only direct effect they have. For +example, if you `clear(auto)`, you will see the following in the output. + +``` my_file +clear(auto). + % clear(auto) -> clear(auto_inference). + % clear(auto_inference) -> clear(predicate_elim). + % clear(auto_inference) -> assign(eq_defs, pass). + % clear(auto) -> clear(auto_limits). + % clear(auto_limits) -> assign(max_weight, 2147483647). + % clear(auto_limits) -> assign(sos_limit, -1). +``` + +The lines starting with "`%`" are the dependent options that are changed +in behalf of `clear(auto)`. Note the sub-dependencies in this example. + +The option dependencies can be undone by simply changing the dependent +option afterward, as in the following example input. + +``` my_file +clear(auto). +set(predicate_elim). +``` + +## Option Listing + +The option names below are links to the sections containing the +descriptions. + +### From Page [Clauses and Formulas](syntax.html) + +``` my_option +set(prolog_style_variables). +clear(prolog_style_variables). % default clear +``` + +### From Page [Automatic Modes](auto.html) + +``` my_option +set(auto). % default set +clear(auto). +``` + +``` my_option +set(auto_inference). % default set +clear(auto_inference). +``` + +``` my_option +set(auto_process). % default set +clear(auto_process). +``` + +``` my_option +set(auto_setup). % default set +clear(auto_setup). +``` + +``` my_option +set(auto_limits). % default set +clear(auto_limits). +``` + +``` my_option +set(auto2). +clear(auto2). % default clear +``` + +``` my_option +assign(lrs_ticks, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(lrs_interval, n). % default n=50, range [1 .. INT_MAX] +``` + +``` my_option +assign(min_sos_limit, n). % default n=0, range [0 .. INT_MAX] +``` + +``` my_option +set(raw). +clear(raw). % default clear +``` + +### From Page [Term Ordering](term-order.html) + +``` my_option +assign(order, string). % default string=lpo, range [lpo,rpo,kbo] +``` + +``` my_option +set(inverse_order). % default set +clear(inverse_order). +``` + +``` my_option +assign(eq_defs, string). % default string=unfold, range [unfold,fold,pass] +``` + +### From Page [More Search Prep](more-prep.html) + +``` my_option +set(expand_relational_defs). +clear(expand_relational_defs). % default clear +``` + +``` my_option +set(predicate_elim). % default set +clear(predicate_elim). +``` + +``` my_option +assign(fold_denial_max, n). % default n=0, range [-1 .. INT_MAX] +``` + +``` my_option +set(sort_initial_sos). +clear(sort_initial_sos). % default clear +``` + +``` my_option +set(process_initial_sos). % default set +clear(process_initial_sos). +``` + +### From Page [Search Limits](limits.html) + +``` my_option +assign(sos_limit, n). % default n=20000, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_given, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_kept, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_megs, n). % default n=200, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_seconds, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_minutes, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_hours, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_days, n). % default n=-1, range [-1 .. INT_MAX] +``` + +### From Page [Selecting the Given Clause](select.html) + +``` my_option +assign(age_part, n). % default n=1, range [0 .. INT_MAX] +``` + +``` my_option +assign(weight_part, n). % default n=0, range [0 .. INT_MAX] +``` + +``` my_option +assign(false_part, n). % default n=4, range [0 .. INT_MAX] +``` + +``` my_option +assign(true_part, n). % default n=4, range [0 .. INT_MAX] +``` + +``` my_option +assign(random_part, n). % default n=0, range [0 .. INT_MAX] +``` + +``` my_option +assign(hints_part, n). % default n=INT_MAX, range [0 .. INT_MAX] +``` + +``` my_option +set(default_parts). % default set +clear(default_parts). +``` + +``` my_option +assign(pick_given_ratio, n). % default n=0, range [0 .. INT_MAX] +``` + +``` my_option +set(lightest_first). +clear(lightest_first). % default clear +``` + +``` my_option +set(breadth_first). +clear(breadth_first). % default clear +``` + +``` my_option +set(random_given). +clear(random_given). % default clear +``` + +``` my_option +assign(random_seed, n). % default n=0, range [-1 .. INT_MAX] +``` + +``` my_option +set(input_sos_first). % default set +clear(input_sos_first). +``` + +### From Page [Inference Rules](inf-rules.html) + +``` my_option +set(binary_resolution). +clear(binary_resolution). % default clear +``` + +``` my_option +set(neg_binary_resolution). +clear(neg_binary_resolution). % default clear +``` + +``` my_option +set(ordered_res). % default set +clear(ordered_res). +``` + +``` my_option +set(check_res_instances). +clear(check_res_instances). % default clear +``` + +``` my_option +assign(literal_selection, string). % default string=max_negative, range [max_negative, all_negative, none] +``` + +``` my_option +set(pos_hyper_resolution). +clear(pos_hyper_resolution). % default clear +``` + +``` my_option +set(hyper_resolution). +clear(hyper_resolution). % default clear +``` + +``` my_option +set(neg_hyper_resolution). +clear(neg_hyper_resolution). % default clear +``` + +``` my_option +set(ur_resolution). +clear(ur_resolution). % default clear +``` + +``` my_option +set(pos_ur_resolution). +clear(pos_ur_resolution). % default clear +``` + +``` my_option +set(neg_ur_resolution). +clear(neg_ur_resolution). % default clear +``` + +``` my_option +set(initial_nuclei). +clear(initial_nuclei). % default clear +``` + +``` my_option +assign(ur_nucleus_limit, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +set(paramodulation). +clear(paramodulation). % default clear +``` + +``` my_option +set(ordered_para). % default set +clear(ordered_para). +``` + +``` my_option +set(check_para_instances). +clear(check_para_instances). % default clear +``` + +``` my_option +set(para_from_vars). % default set +clear(para_from_vars). +``` + +``` my_option +assign(para_lit_limit, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +set(para_units_only). +clear(para_units_only). % default clear +``` + +``` my_option +set(basic_paramodulation). +clear(basic_paramodulation). % default clear +``` + +### From Page [Processing Inferred Clauses](process-inf.html) + +``` my_option +set(lex_order_vars). +clear(lex_order_vars). % default clear +``` + +``` my_option +assign(demod_step_limit, n). % default n=1000, range [-1 .. INT_MAX] +``` + +``` my_option +assign(demod_increase_limit, n). % default n=1000, range [-1 .. INT_MAX] +``` + +``` my_option +set(back_demod). % default set +clear(back_demod). +``` + +``` my_option +set(lex_dep_demod). % default set +clear(lex_dep_demod). +``` + +``` my_option +assign(lex_dep_demod_lim, n). % default n=11, range [-1 .. INT_MAX] +``` + +``` my_option +set(lex_dep_demod_sane). % default set +clear(lex_dep_demod_sane). +``` + +``` my_option +set(unit_deletion). +clear(unit_deletion). % default clear +``` + +``` my_option +set(cac_redundancy). % default set +clear(cac_redundancy). +``` + +``` my_option +assign(max_literals, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_depth, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_vars, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(max_weight, n). % default n=100, range [INT_MIN .. INT_MAX] +``` + +``` my_option +set(safe_unit_conflict). +clear(safe_unit_conflict). % default clear +``` + +``` my_option +set(factor). +clear(factor). % default clear +``` + +``` my_option +assign(new_constants, n). % default n=0, range [-1 .. INT_MAX] +``` + +``` my_option +set(back_subsume). % default set +clear(back_subsume). +``` + +``` my_option +assign(backsub_check, n). % default n=500, range [-1 .. INT_MAX] +``` + +### From Page [Output Files](output.html) + +``` my_option +set(echo_input). % default set +clear(echo_input). +``` + +``` my_option +set(quiet). +clear(quiet). % default clear +``` + +``` my_option +set(print_initial_clauses). % default set +clear(print_initial_clauses). +``` + +``` my_option +set(print_given). % default set +clear(print_given). +``` + +``` my_option +set(print_gen). +clear(print_gen). % default clear +``` + +``` my_option +set(print_kept). +clear(print_kept). % default clear +``` + +``` my_option +set(print_labeled). +clear(print_labeled). % default clear +``` + +``` my_option +set(print_clause_properties). +clear(print_clause_properties). % default clear +``` + +``` my_option +set(print_proofs). % default set +clear(print_proofs). +``` + +``` my_option +set(default_output). % default set +clear(default_output). +``` + +``` my_option +assign(report, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(stats, string). % default string=lots, range [none,some,lots,all] +``` + +``` my_option +set(clocks). +clear(clocks). % default clear +``` + +``` my_option +set(bell). % default set +clear(bell). +``` + +### From Page [Weighting](weight.html) + +``` my_option +assign(constant_weight, n). % default n=1, range [INT_MIN .. INT_MAX] +``` + +``` my_option +assign(sk_constant_weight, n). % default n=1, range [INT_MIN .. INT_MAX] +``` + +``` my_option +assign(variable_weight, n). % default n=1, range [INT_MIN .. INT_MAX] +``` + +``` my_option +assign(not_weight, n). % default n=0, range [INT_MIN .. INT_MAX] +``` + +``` my_option +assign(or_weight, n). % default n=0, range [INT_MIN .. INT_MAX] +``` + +``` my_option +assign(prop_atom_weight, n). % default n=1, range [INT_MIN .. INT_MAX] +``` + +``` my_option +assign(nest_penalty, n). % default n=0, range [0 .. INT_MAX] +``` + +``` my_option +assign(depth_penalty, n). % default n=0, range [INT_MIN .. INT_MAX] +``` + +``` my_option +assign(var_penalty, n). % default n=0, range [INT_MIN .. INT_MAX] +``` + +``` my_option +assign(default_weight, n). % default n=INT_MAX, range [INT_MIN .. INT_MAX] +``` + +### From Page [Goals and Denials](goals.html) + +``` my_option +assign(max_proofs, n). % default n=1, range [-1 .. INT_MAX] +``` + +``` my_option +set(reuse_denials). +clear(reuse_denials). % default clear +``` + +``` my_option +set(auto_denials). % default set +clear(auto_denials). +``` + +``` my_option +set(restrict_denials). +clear(restrict_denials). % default clear +``` + +### From Page [Hints](hints.html) + +``` my_option +set(breadth_first_hints). +clear(breadth_first_hints). % default clear +``` + +``` my_option +set(degrade_hints). % default set +clear(degrade_hints). +``` + +``` my_option +set(limit_hint_matchers). +clear(limit_hint_matchers). % default clear +``` + +``` my_option +set(back_demod_hints). % default set +clear(back_demod_hints). +``` + +``` my_option +set(collect_hint_labels). +clear(collect_hint_labels). % default clear +``` + +### From Page [Semantic Guidance](semantics.html) + +``` my_option +assign(multiple_interps, string). % default string=false_in_all, range [false_in_all, false_in_some] +``` + +``` my_option +assign(eval_limit, n). % default n=1024, range [-1 .. INT_MAX] +``` + +------------------------------------------------------------------------ + +Next Section: [Glossary](glossary.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Automatic Modes + +> Prover9's automatic mode is set by default. Otter's automatic mode +> must be explicitly set. + +If you simply give Prover9 a set of clauses and/or formulas, Prover9 +will look at the clauses and decide which inference rules and +clause-processing operations to use. If you don't like the automatic +decisions that Prover9 makes, you can clear the flag +[**`auto`**](auto.html#auto) or any of the secondary auto flags that +depend on it. Prover9 output files show in detail the effects of +changing these flags. + +``` my_option +set(auto). % default set +clear(auto). +``` + +> This is the basic automatic mode of Prover9. The only direct effect of +> this flag is that it changes four secondary auto flags as follows. +> +> set(auto) -> set(auto_inference). +> set(auto) -> set(auto_process). +> set(auto) -> set(auto_setup). +> set(auto) -> set(auto_limits). +> set(auto) -> set(auto_denials). +> +> clear(auto) -> clear(auto_inference). +> clear(auto) -> clear(auto_process). +> clear(auto) -> clear(auto_setup). +> clear(auto) -> clear(auto_limits). +> clear(auto) -> clear(auto_denials). +> +> Any of the secondary flags, as well as the entire automatic mode can +> be cleared by the user. + +``` my_option +set(auto_inference). % default set +clear(auto_inference). +``` + +> If this flag is set, the input clauses are checked for several +> syntactic properties such as the presence of equality and +> [non-Horn](glossary.html#horn) clauses. Based on the results of the +> checks, Prover9 decides which inference rules to use. +> +> Unlike ordinary option dependencies, the options that are changed by +> [**`auto_inference`**](auto.html#auto_inference) cannot be undone by +> placing commands in the input file, because they depend on the +> structure of the clauses. + +``` my_option +set(auto_process). % default set +clear(auto_process). +``` + +> This flag causes several other flags that affect clause processing to +> be altered based syntactic properties of the initial clauses. +> +> If all clauses are Horn and there are negative nonunits, the flag +> [**`back_unit_deletion`**](process-inf.html#back_unit_deletion) is +> automatically set. If there are non-Horn clauses, the flags +> [**`back_unit_deletion`**](process-inf.html#back_unit_deletion) and +> [**`factor`**](process-inf.html#factor) are automatically set. +> +> Unlike ordinary option dependencies, the options that are changed by +> [**`auto_process`**](auto.html#auto_process) cannot be undone by +> placing commands in the input file, because they depend on the +> structure of the clauses. + +``` my_option +set(auto_setup). % default set +clear(auto_setup). +``` + +> The only effect of changing this flag is that two parameters are +> changed in the following ways. +> +> set(auto_setup) -> set(predicate_elim). +> set(auto_setup) -> assign(eq_defs, unfold). +> +> clear(auto_setup) -> clear(predicate_elim). +> clear(auto_setup) -> assign(eq_defs, pass). + +``` my_option +set(auto_limits). % default set +clear(auto_limits). +``` + +> The only effect of changing this flag is that two parameters are +> changed in the following ways. +> +> set(auto_limits) -> assign(max_weight, 100). +> set(auto_limits) -> assign(sos_limit, 10000). +> +> clear(auto_limits) -> assign(max_weight, INT_MAX). +> clear(auto_limits) -> assign(sos_limit, -1). + +## An Experimental Automatic Mode + +``` my_option +set(auto2). +clear(auto2). % default clear +``` + +> This is an enhanced automatic mode, developed in preparation for +> CASC-2005. The only direct effect of changing this option is that it +> causes several other options to be changed. See an output file to see +> the effects of setting this flag. + +## Automatically Adjusting the [**`sos_limit`**](limits.html#sos_limit) Parameter + +``` my_option +assign(lrs_ticks, n). % default n=-1, range [-1 .. INT_MAX] +``` + +``` my_option +assign(lrs_interval, n). % default n=50, range [1 .. INT_MAX] +``` + +``` my_option +assign(min_sos_limit, n). % default n=0, range [0 .. INT_MAX] +``` + +> These three parameters work together and are used to automatically +> adjust the parameter [**`sos_limit`**](limits.html#sos_limit) by means +> of a "limited resource strategy" \[[RV-lrs](references.html#RV-lrs)\]. +> If [**`lrs_ticks`**](auto.html#lrs_ticks) ≥ 0, the method is applied. +> +> This is an experimental feature and is not recommended for general +> use. + +## Raw Mode + +The default values of the options can interfere with specialized search +strategies. To avoid some of those problems, one can start from scratch +by setting the following option. + +``` my_option +set(raw). +clear(raw). % default clear +``` + +> This is a sort of anti-automatic mode, which allows the user to +> completely specify the search strategy, with less chance of +> interference from the default settings of various options. For +> example, to generate all binary resolvents, one can simply set the +> flags `raw` and +> [**`binary_resolution`**](inf-rules.html#binary_resolution) instead of +> finding and clearing the flags that restrict resolution. +> +> The flag works by making the following changes. +> +> set(raw) -> clear(auto). +> clear(auto) -> clear(auto_inference). +> clear(auto) -> clear(auto_setup). +> clear(auto_setup) -> clear(predicate_elim). +> clear(auto_setup) -> assign(eq_defs, pass). +> clear(auto) -> clear(auto_limits). +> clear(auto_limits) -> assign(max_weight, 2147483647). +> clear(auto_limits) -> assign(sos_limit, -1). +> clear(auto) -> clear(auto_denials). +> clear(auto) -> clear(auto_process). +> set(raw) -> clear(ordered_res). +> set(raw) -> clear(ordered_para). +> set(raw) -> assign(literal_selection, none). +> set(raw) -> clear(back_demod). +> set(raw) -> clear(cac_redundancy). +> set(raw) -> assign(backsub_check, 2147483647). +> set(raw) -> set(lightest_first). +> set(lightest_first) -> assign(weight_part, 1). +> set(lightest_first) -> assign(age_part, 0). +> set(lightest_first) -> assign(false_part, 0). +> set(lightest_first) -> assign(true_part, 0). +> set(lightest_first) -> assign(random_part, 0). + +------------------------------------------------------------------------ + +Next Section: [Term Ordering](term-order.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Output Files + +Even when Prover9 fails to find a proof, its output file usually has +lots of valuable information about the search. The output file can +suggest many ways of improving the search for subsequent jobs as in the +following examples. + +- The output shows how equalities are oriented; different [term ordering + parameters](term-order.html) may give better or more intuitive + orientations. +- If Prover9 focused the search on uninteresting clauses (see the + sequence of given clauses), different [inference + rules](inf-rules.html), a different + [**`pick_given_ratio`**](select.html#pick_given_ratio), or a + specialized [weighting function](weight.html) can be used. +- If Prover9 ran out of time or memory with a huge `sos` list and small + `usable` list (i.e., few given clauses were used), the + [**`sos_limit`**](limits.html#sos_limit) should be reduced. + +## Basic Structure of Output Files + +Prover9 output files are divided into sections and subsections so the +users (people and programs) can find what they are looking for. The +delimiters are self-explanatory. A few comments about the sections are +given here. For a specific example, see the output file +[subset_trans.out](subset_trans.out). + +``` my_file +============================== Prover9 =============================== + Version, date, host computer, command. +============================== end of head =========================== + +============================== INPUT ================================= + Echo of the input. Everything in this section that is not + in the input is commented with "%", so copy-and-paste can be + done on this section to create a new input file. +============================== end of input ========================== + +============================== PROCESS GOALS ========================= + The search is always by refutation, and this section shows + how goals are negated in preparation for the search. +============================== end of process goals ================== + +============================== PROCESS INITIAL CLAUSES =============== + This section shows the starting clauses (after Skomemization, + if applicable) and then some of what Prover9 does in preparation + for the search. This includes predicate_elim, term ordering + decisions, and auto_inference settings. At this stage, clauses + may be deleted by subsumption and equations may be copied to the + list demodulators. See the flag process_initial_sos. +============================== end of process initial clauses ======== + +============================== CLAUSES FOR SEARCH ==================== + This section shows the clauses just before the start of the + search, that is, just before selection of the first given clause. + +============================== end of clauses for search ============= + +============================== SEARCH ================================ + This section typically shows the sequence of given clauses, + and it may also include PROOF and STATISTICS sections. + +============================== PROOF ================================= + A proof in standard form. +============================== end of proof ========================== + +============================== STATISTICS ============================ + We encourage users to look at statistics! +============================== end of statistics ===================== + +============================== end of search ========================= +``` + +## Clause Justifications + +After the initial stage of the output, each clause in the file has an +integer identifier (ID) and a justification that may refer to IDs of +other clauses. A justification is a list consisting of one primary step +and some number of secondary steps. Most primary steps are inference +rules applied to given clauses, and most secondary steps consist of +simplification, rewriting, or orienting equalities. + +Many of the types of step refer to positions of literals or terms in the +parent clauses. Literals are identified by the characters 'a' (first +literal), 'b' (second literal), etc. Terms are identified by the literal +identifier followed by a sequence of integers giving the position of the +term within the literal. For example, the position 'c,1,3,2' means third +literal, first argument, third argument, second argument. Negation signs +on literals are not included in the sequence. + +Primary Steps. + +- `assumption` -- input formula. +- `clausify` -- from CNF translation of a non-clausal assumption. +- `goal` -- input formula. +- `deny` -- from CNF translation of the negation of a goal. +- `resolve(59,b,47,c)` -- resolve the second literal of clause 59 with + the third literal of clause 47. +- `hyper(59, b,47,a, c,38,a)` -- hyperresolution; interpret the list as + a clause ID followed by a sequence of triples, + \ the inference is presented as a sequence + of binary resolution steps. In the example shown, start with clause + 59; then resolve literal b with clause 47 on literal a; with the + result of the first step, resolve literal c with clause 38 on + literal a. The special case "`xx`" means resolution with `x=x`. +- `ur(39, a,48,a, b,88,a, c,87,a, d,86,a)` -- unit-resulting resolution; + the list is interpreted as in hyperresolution. +- `para(47(a,1),28(a,1,2,2,1))` -- paramodulate from the clause 47 into + clause 28 at the positions shown. +- `copy(59)` -- copy clause 59. +- `back_rewite(59)` -- copy clause 59. +- `back_unit_del(59)` -- copy clause 59. +- `new_symbol(59)` -- introduce a new constant (see parameter + [**`new_constants`**](inf-rules.html#new_constants)). +- `factor(59,b,c)` -- factor clause 59 by unifying the second and third + literals. +- `xx_res(59,b)` -- resolve the second literal of clause 59 with `x=x`. +- `propositional` -- not used in standard proofs. +- `instantiate` -- not used in standard proofs. +- `ivy` -- not used in standard proofs. + +Secondary Steps (each assumes a working clause, which is either the +result of a primary step or a previous secondary step). + +- `rewrite([38(5,R),47(5),59(6,R)])` -- rewriting (demodulation) with + equations 38, 47, then 59; the arguments (5), (5), and (6) identify + the positions of the rewritten subterms (in an obscure way), and the + argument R indicates that the demodulator is used backward + (right-to-left). +- `flip(c)` -- the third literal is an equality that has been flipped by + the term ordering. This does not necessarily mean that the equality is + orientable by the primary term ordering, e.g., KBO. +- `merge(d)` -- the fourth literal has been removed because it was + identical to a preceding literal. +- `unit_del(b,38)` -- the second literal has been removed because it was + an instance of the negation clause 38 (which is a unit clause). +- `xx(b)` -- the second literal has been removed because it was an + instance of `x!=x`. + +## Standard Proofs + +Prover9 proofs may be transformed by separate programs, e.g., by +[Prooftrans](prooftrans.html). + +## Options That Say What Goes To the Output File + +``` my_option +set(echo_input). % default set +clear(echo_input). +``` + +> Clearing this flag suppresses printing of clauses, formulas, weighting +> rules (and everything else that ends with `end_of_list`) that would +> ordinarily appear in the `INPUT` section of the output file. + +``` my_option +set(quiet). +clear(quiet). % default clear +``` + +> Setting this flag causes most messages to the standard error file +> (usually the user's screen) to be suppressed. These messages include +> notifications about proofs and statistics reports, and warnings about +> demodulation limits. Setting this flag also suppresses several +> messages to the ordinary output file, and it clears the +> [**`bell`**](output.html#bell) flag. + +``` my_option +set(print_initial_clauses). % default set +clear(print_initial_clauses). +``` + +> If this flag is set, clauses are printed in the +> `PROCESS INITIAL CLAUSES` and `CLAUSES FOR SEARCH` sections of the +> output file. + +``` my_option +set(print_given). % default set +clear(print_given). +``` + +> Clearing this flag prevents given clauses from being printed to the +> output file. + +``` my_option +set(print_gen). +clear(print_gen). % default clear +``` + +> Setting this flag causes all generated clauses to be printed to the +> the output file. In addition, some other information about the +> processing of each generated clause is printed. This flag can be +> output files to be really huge. + +``` my_option +set(print_kept). +clear(print_kept). % default clear +``` + +> Setting this flag causes all kept clauses to be printed to the the +> output file. In addition, some other information on the processing of +> kept clauses is printed. + +``` my_option +set(print_labeled). +clear(print_labeled). % default clear +``` + +> Setting this flag causes kept clauses containing label attributes to +> be printed, even when the flag +> [**`print_kept`**](output.html#print_kept) is clear. This flag is +> useful when using [the hints strategy](hints.html), because when a +> clause matches a hint containing a label, the label is copied to the +> clause. That is, clauses matching labeled hints will be printed. + +``` my_option +set(print_clause_properties). +clear(print_clause_properties). % default clear +``` + +> Setting this flag causes several properties of clauses to be printed +> as "props" attributes on the clauses. The properties include which +> literals are maximal (counting from 1), which literals are maximal +> among literals of the same sign, and which literals are selected for +> application of inference rules. + +``` my_option +set(print_proofs). % default set +clear(print_proofs). +``` + +> Clearing this flag prevents proofs from being printed to the output +> file. The proof message still goes to the standard error file (usually +> the user's screen), unless the flag [**`quiet`**](output.html#quiet) +> has been set. + +``` my_option +set(default_output). % default set +clear(default_output). +``` + +> Setting this flag restores most of the output flags and parameters to +> their default values. Clearing this flag does nothing. + +``` my_option +assign(report, n). % default n=-1, range [-1 .. INT_MAX] +``` + +> If *n* \> 0, statistics are sent to the output file approximately +> every *n* seconds. (On Unix-like systems, one can also tell Prover9 to +> print statistics to the output file by sending the signal `USR1` to a +> running Prover9 process, e.g., `kill -USR1 4223`.) + +``` my_option +assign(stats, string). % default string=lots, range [none,some,lots,all] +``` + +> This parameter determines how many statistics are sent to the output +> file. + +``` my_option +set(clocks). +clear(clocks). % default clear +``` + +> If this flag is set, various operations during the Prover9 job are +> timed (e.g., inference, demodulation, and subsumption), and timing +> reports are sent to the output file. +> +> Timing the operations can be expensive, especially in Solaris and +> Macintosh systems. On Linux systems, `set(clocks)` typically adds 5% +> -- 10% to the run time. + +``` my_option +set(bell). % default set +clear(bell). +``` + +> If this flag is set, Prover9 beeps when important things happen, such +> as proofs and warnings. Some users run searches that find hundreds of +> proofs, and they clear this flag to prevent all of the beeping. + +------------------------------------------------------------------------ + +Next Section: [Weighting](weight.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Mace4 (Models And CounterExamples) + +The program [Mace4](http://www.cs.unm.edu/~mccune/mace4/) +\[[McCune-Mace4](references.html#McCune-Mace4)\] searches for finite +structures satisfying first-order and equational statements (the same +kind of statement that Prover9 accepts). If the statement is the denial +of some conjecture, any structures found by Mace4 are counterexamples to +the conjecture. + +Mace4 can be a valuable complement to Prover9, looking for +counterexamples before (or at the same time as) using Prover9 to search +for a proof. It can also be used to help debug input clauses and +formulas for Prover9. + +For the most part, Mace4 accepts the same input files as Prover9. If the +input file contains commands that Mace4 does not understand, then the +argument "-c" must be given to tell Mace4 to ignore those commands. + +For example, say we're learning group theory, and we're wondering +whether all groups are commutative. We can run the following two jobs in +parallel, with Prover9 looking for a proof, and Mace4 looking for a +counterexample. + +``` my_job +prover9 -f x2.in > x2.prover9.out +mace4 -c -f x2.in > x2.mace4.out +``` + +Most of the options accepted by Mace4 can be given either on the command +line or in the input file. The following command lists the command-line +options accepted by Mace4. + +``` my_job +mace4 -help +``` + +**Terminology**. We use the terms *interpretation*, *model*, and +*structure* for the objects that Mace4 produces. From a logic point of +view, Mace4 produces interpretations which are models of the input +formulas. From a math point of view, Mace4 produces structures +satisfying the input formulas. + +## What Mace4 Does + +Mace4 searches for *unsorted finite structures* only. That is, a +structure (model) has one underlying finite set, called the *domain* +(the members are always 0,1,...,*n-1* for a set of size *n*), and +structures are functions and relations (tables) over the domain, +corresponding to the operations and relation symbols in the +specification. + +By default, Mace4 starts searching for a structure of domain size 2, and +then it increments the size until it succeeds or reaches some limit. + +## The Original Mace4 Manual + +The original Mace4 manual +\[[McCune-Mace4](references.html#McCune-Mace4)\] +([PDF)](http://www.cs.unm.edu/~mccune/prover9/mace4.pdf) is out of date +with respect to features and options, but it contains useful information +on the history of Mace4, details on the search methods, and the +differences between Mace2 and Mace4. + +------------------------------------------------------------------------ + +Next Section: [Mace4 Input](m4-input.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Mace4 Input + +Mace4 has been designed so that it accepts most Prover9 input files. +This allows users to prepare one input file which can be used by Prover9 +(to search for proofs) and by Mace4 (to search for counterexamples). + +## Mace4 Options + +Mace4 and Prover9 accept different sets of flags and parameters. In +order to use the same input files for both programs, we let Mace4 take +its options from the command line instead of from the input file. If +Mace4 is given a Prover9 input file, along with the command-line option +`-c`, it will ignore any unrecognized (e.g., Prover9) options in the +input file. The Mace4 options are described on the [next +page](m4-options.html). + +## Formulas (including Clauses) + +Mace4 accepts the same formulas and clauses as Prover9. See the page +[Prover9 Clauses and Formulas](syntax.html). + +### *A Caveat: Domain Elements* + +> In one important case, formulas have different meanings in Prover9 and +> Mace4: + +If a formula contains constants that are natural-numbers, {0,1,...}, +Mace4 assumes they are members of the domain of some structure, that is, +they are distinct objects; in effect, Mace4 operates under the +assumptions 0 ≠ 1, 0 ≠ 2, ... . + +To Prover9, natural numbers are just ordinary constants. For example, to +Prover9 the statement 0=1 is satisfiable, and to Mace4 it is +unsatisfiable. + +Because Mace4 assumes that natural-number constants are members of the +domain, if a formula contains a natural number that is out of range (≥ +*n*), when searching for a structure of size *n*), Mace4 will terminate +its search for size *n* (and continue with larger sizes if the +specification says to do so). + +*An Exception.* When the flag `arithmetic` is set, natural numbers +outside of {0,1,...,n-1} can occur. + +## Lists of Formulas (including Clauses) + +Prover9 accepts a fixed set of lists of formulas (e.g., `assumptions`, +`usable`, `goals`, `hints`). + +Mace4 accepts any lists of formulas. All are treated as ordinary +formulas *except the following two lists*. + +- `formulas(hints)`. These are intended to help Prover9 find proofs and + are ignored by Mace4. +- `formulas(goals)`. These are negated by Mace4, just as they are by + Prover9. + +### `formulas(goals)` + +Prover9 has several restrictions on the goals it accepts (see [Prover9 +Goals and Denials](goals.html)), and Mace4 has the same restrictions. +Mace4 negates goals and translates them to clauses in the same way as +Prover9. (The term "goal" might seem to be bad teminology for Mace4 +users, because Mace4 does not prove theorems; however, one can think of +Mace4 as searching for a counterexample to the goal.) + +When there are multiple goals, Mace handles them the same as Prover9. +For example, consider the following goals. + +``` my_file +formulas(goals). + x * y = y * x # label(commutativity). + (x * y) * z = x * (y * z) # label(associativity). +end_of_list. +``` + +Logically, this is a disjunction: Prover9 gives a proof if either goal +is proved, and Mace4 gives a counterexample if both are falsified. In +particular, this pair of goals is equivalent (for both Prover9 and +Mace4) to the following pair of assumptions. + +``` my_file +formulas(assumptions). + exists x exists y (x * y != y * x). + exists x exists y exists z (x * y) * z != x * (y * z). +end_of_list. +``` + +## Distinct Objects + +Mace4 accepts a shorthand method for stating that sets of objects are +distinct. Here is an example of two sets of distinct objects. + +``` my_file +list(distinct). +[a,b,c]. % equivalent to (a!=b & a!=c & b!=c). +[d,e,f(a)]. % equivalent to (d!=e & d!=f(a) & e!=f(a)). +end_of_list. +``` + +Although `list(distinct)` will probably be used mostly for constants and +other ground terms, terms with variables can occur. + +------------------------------------------------------------------------ + +Next Section: [Mace4 Options](m4-options.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Mace4 Options + +Mace4 accepts `set`, `clear`, and `assign` commands in the input file. +Several of these are in common with Prover9 (e.g., +`assign(max_seconds, 30)`), but most are specifically for Mace4. + +If Mace4 is called with the command-line option `-c` (compatability +mode), it will ignore any `set`, `clear`, and `assign` that it does not +recognize, assuming they are meant for some other program (Prover9). + +Most Mace4 options can be specified on the command line instead of in +the input file. When Mace4 options are specified on the command line, +single-character codes are used. For example, the command-line option +`-t 30` means the same as `assign(max_second, 30)` in the input file. If +an option is given in *both* places, the one on the command line takes +precedence. Command-line options for Boolean-valued options (flags) +always take an argument: 1 means "set", and 0 means "clear". For +example, `-V 1` means `set(prolog_style_vaiables`, and `-V 0` means +`clear(prolog_style_variables)`. + +The command "`mace4 -help`" shows the correspondence between the +command-line codes and the option names, and it shows the default +values. + +## Symbol Ordering + +Like Prover9, Mace4 accepts `function_order` and `relation_order` +commands that specify an order on the symbols in the problem. The syntax +of the commands is the [same as in +Prover9](term-order.html#lex_command), for example, + +``` my_file +predicate_order([=, <=, P, Q]). % = < P < Q +function_order([a, b, c, +, *, h, g]). % a < b < c < + < * < h < g +``` + +Mace4's the default symbol order is the [same as +Prover9's](term-order.html#default_lex). As in Prover9, function symbols +are always less than predicate symbols. + +The symbol order can have a big effect on the time it takes to find a +model or exhaust a domain size, because it determines the order in which +Mace4 tries to fill in the function and relation tables. Unfortunately, +we do not know of any general-purpose heuristics for selecting a good +symbol order. If Mace4 takes too long to go through a particular domain +size, we suggest trying a different symbol order. + +## Option Listing + +### Basic Options + +``` my_file +assign(start_size, n). % default n=2, range [2 .. INT_MAX] % command-line -n n +``` + +``` my_file +assign(end_size, n). % default n=-1, range [-1 .. INT_MAX] % command-line -N n +``` + +``` my_file +assign(increment, n). % default n=1, range [1 .. INT_MAX] % command-line -i n +``` + +These three parameter work together to determine the domain sizes to be +searched. The search starts for structures of size `start_size`; if that +search fails, the size is incremented, and another search starts. This +continues up through the value `end_size` (or until some other limit +terminates the process). If `end_size` is -1, there is no limit. (Also +see the `iterate` parameter below.) + +For example, the command-line options "`-n 5 -N 11 -i 2`" say to try +domain sizes 5,7,9,11. + +``` my_file +assign(domain_size, n). % default n=0, range [0 .. INT_MAX] % command-line -n n +``` + +This parameter says to search *only* the given size. This (meta-) +parameter works simply by making the following changes. + + assign(domain_size, n) -> assign(start_size, n). + assign(domain_size, n) -> assign(end_size, n). + +``` my_file +assign(iterate, string). % default string=all, range [all,evens,odds,primes,nonprimes] +``` + +The `iterate` parameter can be used to add an additional constraint to +the domain sizes. It can be used together with the `increment` +parameter. The `iterate` parameter cannot be specified on the command +line. + +``` my_file +assign(max_models, n). % default n=1, range [-1 .. INT_MAX] % command-line -m n +``` + +The parameter `max_models` says to stop searching when the *n*-th +structure has been found. A value of -1 means there is no limit. + +``` my_file +assign(max_seconds, n). % default n=-1, range [-1 .. INT_MAX] % command-line -t n +``` + +The parameter [**`max_seconds`**](limits.html#max_seconds) says to stop +searching after *n* seconds. A value of -1 means there is no limit. + +``` my_file +assign(max_seconds_per, n). % default n=-1, range [-1 .. INT_MAX] % command-line -s n +``` + +The parameter allows at most *n* seconds for each domain size. The +parameter [**`max_seconds`**](limits.html#max_seconds) can be used +(together with `max_seconds_per`) to given an overall time limit. A +value of -1 means there is no limit. + +``` my_file +assign(max_megs, n). % default n=200, range [-1 .. INT_MAX] % command-line -b n +``` + +The parameter [**`max_megs`**](limits.html#max_megs) says to stop +searching when (about) *n* megabytes of memory have been used. A value +of -1 means there is no limit. + +``` my_file +set(prolog_style_variables). % command-line -V 1 +clear(prolog_style_variables). % default clear % command-line -V 0 +``` + +A rule is needed for distinguishing variables from constants in clauses +and formulas with free variables. If this flag is clear, variables start +with (lower case) 'u' through 'z'. If this flag is set, variables in +clauses start with (upper case) 'A' through 'Z' or '\_'. + +``` my_file +set(print_models). % default set % command-line -P 1 +clear(print_models). % command-line -P 0 +``` + +If this flag is set, all structures that are found are printed in +"standard" form, which means they are suitable as input to other LADR +programs such as [isofilter](m4-isofilter.html) and +[interpformat](m4-interpforma.html). + +``` my_file +set(print_models_tabular). % command-line -p 1 +clear(print_models_tabular). % default clear % command-line -p 0 +``` + +If this flag is set, and if is clear, all structures that are found are +printed in a tabular form. If both `print_models` and +`print_models_standard` are set, the last one in the input takes effect. + +``` my_file +set(integer_ring). % command-line -R 1 +clear(integer_ring). % default clear % command-line -R 0 +``` + +If this flag is set, a ring structure is is applied to the search. The +operations {+,-,\*} are assumed to be the ring of integers (mod +domain_size). This method puts a tight constraint on the search, +allowing much larger structures to be investigated. Here is an example. + +``` my_job +mace4 -f ring41.in > ring41.out +``` + +For further information on the `integer_ring` flag, see [slides from a +workshop +presentation](http://www.cs.unm.edu/~mccune/slides/award-2004.pdf). + +``` my_file +set(order_domain). +clear(order_domain). % default clear +``` + +If this flag is set, the relations `<` and `<=` are fixed as order +relations on the domain in the obvious way. + +``` my_file +set(arithmetic). +clear(arithmetic). % default clear +``` + +If this flag is set, several function and relation symbols understood by +Mace4 as operations and relations on the integers, and evaluation of +terms involving those symbols occurs during the search for models. See +the page [Arithmetic for Mace4](m4-arithmetic.html). + +``` my_file +set(verbose). % command-line -v 1 +clear(verbose). % default clear % command-line -v 0 +``` + +If the `verbose` flag is set, the output file receives information about +the search, including the initial partial model (the part of the model +that can be determined before backtracking starts) and timing and other +statistics for each domain size. (It does not give a trace of the +backtracking, so it does not consume a lot of file space.) + +``` my_file +set(trace). % command-line -T 1 +clear(trace). % default clear % command-line -T 0 +``` + +If the `trace` flag is set, detailed information about the search, +including a trace of all assignments and backtracking, is printed to the +standard output. *This flag causes a lot of output, so it should be used +only on small searches*. + +### Advanced Options + +These options are used for experimentation with search methods. They can +be ignored by nearly all users. For descriptions of most of these +options, see the original Mace4 manual +\[[McCune-Mace4](references.html#McCune-Mace4)\] +([PDF)](http://www.cs.unm.edu/~mccune/prover9/mace4.pdf). + +``` my_file +set(lnh). % default set % command-line -L 1 +clear(lnh). % command-line -L 0 +``` + +``` my_file +assign(selection_order, n). % default n=2, range [0 .. 2] % command-line -O n +``` + +``` my_file +assign(selection_measure, n). % default n=4, range [0 .. 4] % command-line -M n +``` + +``` my_file +set(negprop). % default set % command-line -G 1 +clear(negprop). % command-line -G 0 +``` + +``` my_file +set(neg_assign). % default set % command-line -H 1 +clear(neg_assign). % command-line -H 0 +``` + +``` my_file +set(neg_assign_near). % default set % command-line -I 1 +clear(neg_assign_near). % command-line -I 0 +``` + +``` my_file +set(neg_elim). % default set % command-line -J 1 +clear(neg_elim). % command-line -J 0 +``` + +``` my_file +set(neg_elim_near). % default set % command-line -K 1 +clear(neg_elim_near). % command-line -K 0 +``` + +``` my_file +set(skolems_last). % command-line -S 1 +clear(skolems_last). % default clear % command-line -S 0 +``` + +------------------------------------------------------------------------ + +Next Section: [Interpformat](m4-arithmetic.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Interpformat + +The models (structures) in Mace4 output files can be transformed in +various ways with the program Interpformat. + +The transformations are listed here. + +- `standard`: This transformation simply extracts the structure from the + file and reprints it in the same (standard) format, with one line for + each operation. The result should be acceptable to any of the LADR + programs that take standard structures. +- `standard2`: This is similar to `standard`, except that the binary + operations are split across multiple lines to make them more + human-readable. The result should be acceptable to any of the LADR + programs that take standard structures. +- `portable`: This form is list of ... of lists of strings and natural + numbers. It can be parsed by seveal scripting systems such as GAP, + Python, and Javascript. See the section [Portable Format](#portable). +- `tabular`: This form is designed to be easily readable by humans. It + is not meant for input to other programs. +- `raw`: This form is a sequence of natural numbers. +- `cooked`: This form is a sequence of ground terms. +- `xml`: This is an XML form. Here is a [DTD](interp3.dtd) for LADR + interpretations, and here is an [XML stylesheet](interp3.xsl) for + transforming the XML to HTML. +- `tex`: This generates LaTeX source for the interpretation. + +## Examples + +The following Mace4 job creates an output file containing one model in +"standard" (the default) format. + +``` my_job +mace4 -c -f x2.in > x2.mace4.out +``` + +The following Interpformat jobs take the Mace4 output file, extract the +model, and transform it as described above. + +``` my_job +interpformat standard -f x2.mace4.out > x2.standard +interpformat standard2 -f x2.mace4.out > x2.standard2 +interpformat portable -f x2.mace4.out > x2.portable +interpformat tabular -f x2.mace4.out > x2.tabular +interpformat raw -f x2.mace4.out > x2.raw +interpformat cooked -f x2.mace4.out > x2.cooked +interpformat xml -f x2.mace4.out > x2.xml +interpformat tex -f x2.mace4.out > x2.tex +``` + +Portable Format + +The portable format for interpretations can be parsed by several +scriping languages including [Python](http://www.python.org) and +[GAP](http://www.gap-system.org). Here is a counterexample on ternary +relations in lattice theory. The result contains one interpretation of +size 4 containing two binary functions (meet and join), one binary +relation (less-or-equal), two ternary relations, and three constants. + +``` my_job +mace4 -c -f LT-port.in | interpformat portable > LT-port.out +``` + +The result is a list of interpretations: + +- each interpretation is a triple: \[size-of-interpretation (say n), + comments, list-of-operations\]; +- each operation is a 4-tuple: \["function" \| "relation", + name-of-operation, arity, values\]; +- values of operations (domain elememts are \[0 ... n-1\]): + - constant (nullary function): domain element; + - unary function: list of domain elements; + - binary funcion: 2-dimensional list (list of lists) of domain + elements; + - ternary funcion: 3-dimensional list of domain elements; + - etc. + - relations are similar but with values of 0 (FALSE) or 1 (TRUE). + +Here is a simple Python script that reads a list of portable +interpretations and prints them in a different form. + +``` my_job +port.py < LT-port.out > LT-port.out2 +``` + +Here is a simple GAP session that reads and prints a list of portable +interpretations. + +``` my_screen +% gap -b +GAP4, Version: 4.4.7 of 17-Mar-2006, i486-pc-linux-gnu-i486-linux-gnu-gcc +gap> interpretations := EvalString(StringFile("LT-port.out"));; +gap> interpretations; +[ [ 4, [ "=(number,1)", "=(seconds,0)" ], + [ [ "relation", "<=", 2, [ [ 1, 1, 1, 1 ], [ 0, 1, 0, 0 ], + [ 0, 1, 1, 0 ], [ 0, 1, 0, 1 ] ] ], + [ "function", "^", 2, [ [ 0, 0, 0, 0 ], [ 0, 1, 2, 3 ], + [ 0, 2, 2, 0 ], [ 0, 3, 0, 3 ] ] ], + [ "function", "v", 2, [ [ 0, 1, 2, 3 ], [ 1, 1, 1, 1 ], + [ 2, 1, 2, 1 ], [ 3, 1, 1, 3 ] ] ], + [ "function", "c1", 0, 2 ], [ "function", "c2", 0, 0 ], + [ "function", "c3", 0, 3 ], + [ "relation", "A", 3, [ [ [ 1, 1, 1, 1 ], [ 0, 1, 0, 0 ], + [ 0, 1, 1, 0 ], [ 0, 1, 0, 1 ] ], + [ [ 1, 0, 0, 0 ], [ 1, 1, 1, 1 ], [ 1, 0, 1, 0 ], + [ 1, 0, 0, 1 ] ], + [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 1, 1, 1, 0 ], + [ 0, 0, 0, 0 ] ], + [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 0, 0 ], + [ 1, 1, 0, 1 ] ] ] ], + [ "relation", "B", 3, [ [ [ 1, 1, 1, 1 ], [ 0, 1, 0, 0 ], + [ 0, 1, 1, 0 ], [ 0, 1, 0, 1 ] ], + [ [ 1, 0, 0, 0 ], [ 1, 1, 1, 1 ], [ 1, 0, 1, 0 ], + [ 1, 0, 0, 1 ] ], + [ [ 1, 0, 0, 1 ], [ 0, 1, 0, 1 ], [ 1, 1, 1, 1 ], + [ 0, 0, 0, 1 ] ], + [ [ 1, 0, 1, 0 ], [ 0, 1, 1, 0 ], [ 0, 0, 1, 0 ], + [ 1, 1, 1, 1 ] ] ] ] ] ] ] +gap> +``` + +------------------------------------------------------------------------ + +Next Section: [Isofilter](m4-isofilter.html) + + +------------------------------------------------------------------------ + +*Prover9 Manual* + + +*Version 2009-11A* + +------------------------------------------------------------------------ + +# Prooftrans + +When Prover9 proves a theorem, it sends the proof to its output file in +a standard form. The standard form contains, for each step, +[justifications](output.html#just) with enough detail to reconstruct or +check the proof without any search. + +Prover9 proofs may contain non-clausal assumptions and +[goals](goals.html), as well as ordinary clauses. Non-clausal +assumptions are translated to clauses, and goals are negated and then +translated to clauses. See the proof in following example + +``` my_job +prover9 -f subset_trans.in > subset_trans.out +``` + +Prooftrans can extract proofs from Prover9 output files and transform +them in various ways, including the following. + +- No transformation, +- renumber steps, +- simplify justifications, +- expand all steps, turning secondary justifications into explicit + steps, +- produce proofs in XML, +- produce proofs for checking by the IVY proof checker, and +- produce hints for guiding subsequent searches. + +Prooftrans is part of the LADR/Prover9/Mace4 package. When the package +is installed, the Prooftrans program should be in the same directory as +Prover9 and Mace4. + +## Using Prooftrans + +The Prover9 output file containing the proof(s) is usually given to +Prooftrans with the argument "`-f `". If there is no +"`-f `" argument, Prooftrans takes its input from the standard +input. + +The arguments that tell Prooftrans what to do with the proof(s) are +described in the following sections, using the output file +[subset_trans.out](subset_trans.out) as a running example. + +If there is more than one proof in the file, the transformations will be +applied to each proof. The `hints` transformation collects all of the +clauses in the proof(s) into one list of hints. The other +transformations produce one proof for each proof in the input file. + +Here is a synopsis of the Prooftrans command; the arguments in square +brackets are optional. + +``` my_job +prooftrans [parents_only] [expand] [renumber] [striplabels] [-f file] +prooftrans xml [expand] [renumber] [striplabels] [-f file] +prooftrans ivy [renumner] [-f file] +prooftrans hints [-label label] [expand] [striplabels] [-f file] +``` + +Note that more than one transformation can be applied in several cases. +The option "striplabels" tells prooftrans to remove all label attributes +on clauses. + +Unfortunately, the output of Prooftrans usually cannot be used as the +input to another Prooftrans job, because Prooftrans expects its input to +have specific keywords and standard-form proofs. + +------------------------------------------------------------------------ + +### No Transformation + +If no additional argument is given, Prooftrans simply extracts the proof +from the Prover9 output file. + +``` my_job +prooftrans -f subset_trans.out > subset_trans.proof1 +``` + +------------------------------------------------------------------------ + +### Renumber the Steps + +The argument `renumber` tells Prooftrans to renumber the steps of each +proof consecutively, starting with step 1. The `expand`, `parents_only`, +and `xml` transformations can be used with the `renumber` +transformation. + +``` my_job +prooftrans renumber -f subset_trans.out > subset_trans.proof2 +``` + +------------------------------------------------------------------------ + +### Simplify Justifications + +The argument `parents_only` tells Prooftrans list only the parents in +the justifications, not the details about inference rules or positions. +The `expand` and `renumber` transformations can be used with the +`parents_only` transformation. + +``` my_job +prooftrans parents_only -f subset_trans.out > subset_trans.proof3 +``` + +------------------------------------------------------------------------ + +### Expand Steps + +The argument `expand` tells Prooftrans to produce more detailed proofs +in which + +- all hyper- and UR-resolution steps are replaced with binary resolution + steps, +- all demodulation sequences are replaced with paramodulation steps, and +- all unit deletion simplifications are replaced with resolution steps. + +*Note to author: this is a bad example, because only one step gets +expanded.* + +``` my_job +prooftrans expand -f subset_trans.out > subset_trans.proof4 +``` + +Note that when a step is expanded (step 22 in this example), the new +steps are identified by appending 'A', 'B', etc. to the number of the +original step. + +The `renumber`, `parents_only`, and `hints` transformations can be used +with the `expand` transformation. + +------------------------------------------------------------------------ + +### XML Proofs + +The options `xml` or `XML` tell Prooftrans to produce proofs in XML. The +options `expand` and `renumber` can be used with the XML transformation. + +``` my_job +prooftrans xml -f subset_trans.out > subset_trans.proof5.xml +``` + +The preceding output is displayed by your browser not as XML, but as +some transformation of the XML, because the XML refers to an XML +stylesheet, telling the browser how to transform the XML into HTML. + +To see the XML source, click "View -\> Frame Source" (or something like +that) in your browser while viewing the proof. + +Here is the [DTD for Prover9 XML proofs](proof3.dtd). (If you get an +error, click "View -\> Page Source".) + +------------------------------------------------------------------------ + +### IVY Proofs + +The options `ivy` or `IVY` tell Prooftrans to produce very detailed +proofs that can be checked with the [Ivy proof +checker](http://www.cs.unm.edu/~mccune/ivy_check_prover9/). + +``` my_job +prooftrans ivy -f subset_trans.out > subset_trans.proof6 +``` + +Ivy proofs have a only 5 types of step: `input`, `propositional`, +`new_symbol`, `flip`, `instantiate`, `resolve`, and `paramod`. The +`resolve` and `paramod` do not involve unification; instances are +generated first as separate steps, and then `resolve` or `paramod` are +applied to identical atomic formulas or terms. + +The Ivy proof checker cannot check steps justified by `new_symbol`. + +------------------------------------------------------------------------ + +### Proofs to Hints + +The option `hints` tells Prooftrans to take all of the proofs in the +file and produce one list of hints that can be given to Prover9 to guide +subsequent searches on related conjectures. + +``` my_job +prooftrans hints -f subset_trans.out > subset_trans.proof7 +``` + +If there is more than one proof in the file, the proofs will probably +share many steps. The list of hints that Prooftrans produces will be the +union of the steps in the proofs; that is, the duplicate steps will be +removed. + +The `expand` transformation can be used with the `hints` transformation. + +The label option tells prooftrans to attach label attributes to the hint +clauses. The labels consist of the string given on the command line and +a sequence number generated by prooftrans. The user's command shell may +require that the label be quoted, and if the the label is not a legal +LADR constant, prooftrans will enclose the label in double quotes. + +``` my_job +prooftrans hints -label 'job8' -f subset_trans.out > subset_trans.proof8 +``` + +------------------------------------------------------------------------ + +Next Section: [FOF-Prover9](fof-prover9.html) diff --git a/apn/lean/docs/python-flint/LICENSE b/apn/lean/docs/python-flint/LICENSE new file mode 100644 index 00000000..43c2ad50 --- /dev/null +++ b/apn/lean/docs/python-flint/LICENSE @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2014-2016 Fredrik Johansson + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + diff --git a/apn/lean/docs/python-flint/python-flint.md b/apn/lean/docs/python-flint/python-flint.md new file mode 100644 index 00000000..b03c5e42 --- /dev/null +++ b/apn/lean/docs/python-flint/python-flint.md @@ -0,0 +1,375 @@ + +# General concepts + +## Importing + +The `flint` module exposes a set of distinctly-named types together with +a small number of top-level functions and objects. Most functionality is +provided as methods on the types. This means that there should be no +namespace conflicts with most user code, with Python's builtin `math` +and `cmath` modules, or with packages such as `gmpy`, `numpy`, `sympy` +and `mpmath`. For typical interactive use, it should therefore generally +be safe to `import *`: + +> \>\>\> from flint import \* \>\>\> fmpq(3) / 2 3/2 + +For non-interactive use, it is still good manners to use explicit +imports or preserve the `flint` namespace prefix: + + >>> import flint + >>> flint.fmpq(3) / 2 + 3/2 + +## Global context + +Various settings are controlled by a global context object, `flint.ctx`. +Printing this object in the REPL shows the current settings, with a +brief explanation of each parameter: + + >>> from flint import ctx + >>> ctx + pretty = True # pretty-print repr() output + unicode = False # use unicode characters in output + prec = 53 # real/complex precision (in bits) + dps = 15 # real/complex precision (in digits) + cap = 10 # power series precision + threads = 1 # max number of threads used internally + +The user can mutate the properties directly, for example: + + >>> ctx.pretty = False + >>> fmpq(3,2) + fmpq(3,2) + >>> ctx.pretty = True + >>> fmpq(3,2) + 3/2 + +Calling `ctx.default()` restores the default settings. + +The special method `ctx.cleanup()` frees up internal caches used by +MPFR, FLINT and Arb. The user does normally not have to worry about +this. + +The context object `flint.ctx` can be controlled locally to increase the +working precision using python context managers: + + >>> arb(2).sqrt() + [1.41421356237309 +/- 5.15e-15] + >>> with ctx.extraprec(15): + ... arb(2).sqrt() + ... + [1.414213562373095049 +/- 2.10e-19] + +In the same manner, it is possible to exactly set the working precision, +or to update it in terms of digits: + + >>> with ctx.extradps(15): + ... arb(2).sqrt() + ... + [1.41421356237309504880168872421 +/- 6.27e-31] + >>> with ctx.workprec(15): + ... arb(2).sqrt() + ... + [1.414 +/- 2.46e-4] + +## Types and methods + +As a general rule, C functions associated with a type in FLINT or Arb +are exposed as methods of the corresponding Python type. + +For example, there is both an `.fmpq.bernoulli` (which computes a +Bernoulli number as an exact fraction) and `.arb.bernoulli` (which +computes a Bernoulli number as an approximate real number). + +A function that transforms a single value to the same type is usually an +ordinary method of that type, for instance `.arb.exp`. A function with a +different signature can either provided as a static method that takes +all inputs as function arguments, or as a method of the "primary" input, +taking the other inputs as arguments to the method (for example +`.arb.bessel_j`). + +When a method involves different types for inputs and outputs (or just +among the inputs), it will typically be a method of the more "complex" +type. For example, a matrix type is more "complex" than the underlying +scalar type, so `.fmpz_mat.det` is a method of the matrix type, +returning a scalar, and not vice versa. + +The method-based interface is intended to keep the code simple, not to +be aesthetically pleasing to mathematicians. A functional top-level +interface might be added in the future, allowing more idiomatic +mathematical notation (for example, `exp` and `det` as regular +functions). + +## Mutability + +Objects have immutable semantics. For example, the second line in: + + b = a + a += c + +leaves *b* unchanged. + +However, mutation via direct element access is supported for matrices +and polynomials. Some methods also allow explicitly performing the +operation in-place. Civilized users will restrict their use of such +methods to the point in the code where the object is first constructed: + + def create_thing(): # ok + a = thing() + a.mutate() + return a + +## Crashing and burning + +Very little overflow checking is done ahead-of-time. Trying to compute +an object far too large to hold in memory (for example, the exact +factorial of 2^{64}-1) will likely abort +the process, instead of raising an `OverflowError` or `MemoryError` that +can be caught at the Python level. + +Input that is obviously *invalid* (for example a negative number passed +as a length) can also cause crashes or worse things to happen. Ideally, +bad input should be caught at the Python level and result in appropriate +exceptions being raised, but this is not yet done systematically. At +this time, users should assume that invalid input leads to undefined +behavior! + +## Inexact numbers and numerical evaluation + +Real and complex numbers are represented by midpoint-radius intervals +(balls). All operations on real and complex numbers output intervals +representing rigorous error bounds. This also extends to polynomials and +matrices of real and complex numbers. + +The working precision for real and complex arithmetic is controlled by +the global context object attributes `ctx.prec` (in bits) `ctx.dps` (in +decimal digits). Changing either attribute changes the other to match. + +Be careful about using Python float and complex literals as input. Doing +`arb(0.1)` actually gives an interval containing the rational number + +> 3602879701896397 times 2^{-55} = +> 0.1000000000000000055511151231257827021181583404541015625 + +which might not be what you want. Do `arb("0.1")`, `arb("1/10")` or +`arb(fmpq(1,10))` if you want the correct decimal fraction. Small +integers and power-of-two denominators are still safe, for example +`arb(100.25)`. + +Pointwise boolean predicates (such as the usual comparison operators) +involving inexact numbers return *True* only if the predicate certainly +is true (i.e. it holds for all combinations of points that can be chosen +from the set-valued inputs), and return *False* if the predicate either +definitely is false or the truth cannot be determined. To determine that +a predicate is definitely false, test both the predicate and the inverse +predicate, e.g. if either `x < y` or `y <= x` returns *True*, then the +other is definitely false; if both return *False*, then neither can be +determined from the available data. + +The following convenience functions are provided for numerical +evaluation with adaptive working precision. + +## Power series + +Power series objects track the precision (the number of known terms) +automatically. The upper precision for power series is controlled by +`flint.ctx.cap`, with the default value 10. + +> \>\>\> fmpq_series(\[0,1\]).exp() 1 + x + 1/2\*x^2 + 1/6\*x^3 + +> 1/24\*x^4 + 1/120\*x^5 + 1/720\*x^6 + 1/5040\*x^7 + 1/40320\*x^8 + +> 1/362880\*x^9 + O(x^10) \>\>\> ctx.cap = 4 \>\>\> +> fmpq_series(\[0,1\]).exp() 1 + x + 1/2\*x^2 + 1/6\*x^3 + O(x^4) \>\>\> +> ctx.cap = 10 \>\>\> fmpq_series(\[0,1\], prec=5).exp() 1 + x + +> 1/2\*x^2 + 1/6\*x^3 + 1/24\*x^4 + O(x^5) +> +> \>\>\> ctx.cap = 3 \>\>\> ctx.dps = 10 \>\>\> +> arb_series(\[1,3,4\]).exp() (\[2.718281828 +/- 4.79e-10\]) + +> (\[8.154845485 +/- 4.36e-10\])*x + (\[23.10539554 +/- 2.25e-9\])*x^2 + +> O(x^3) \>\>\> ctx.default() + + + +# **fmpz** – integers¶ + +class flint.fmpz(*\*args*)¶ +The *fmpz* type represents an arbitrary-size integer. + + >>> fmpz(3) ** 25 + 847288609443 + + +Methods available on `fmpz` (see upstream docs for details): + + bell_number bin_uiui bit_length divisor_sigma euler_number euler_phi + fac_ui factor factor_smooth fib_ui gcd height_bits + is_perfect_power is_prime is_probable_prime is_square is_zero isqrt + jacobi lcm moebius_mu partitions_p primorial_ui repr + rising root sqrt sqrtmod sqrtrem stirling_s1 + stirling_s2 str + + +# **fmpq** – rational numbers¶ + +class flint.fmpq(*\*args*)¶ +The fmpq type represents multiprecision rational numbers. + + >>> fmpq(1,7) + fmpq(50,51) + 401/357 + + +Methods available on `fmpq` (see upstream docs for details): + + bernoulli ceil dedekind_sum denom floor gcd + harmonic height_bits is_zero next numer repr + round sqrt str trunc + + +# **fmpz_poly** – polynomials over integers¶ + +class flint.fmpz_poly(*\*args*)¶ +The *fmpz_poly* type represents dense univariate polynomials over the +integers. + + >>> fmpz_poly([1,2,3]) ** 3 + 27*x^6 + 54*x^5 + 63*x^4 + 44*x^3 + 21*x^2 + 6*x + 1 + >>> divmod(fmpz_poly([2,0,1,1,6]), fmpz_poly([3,5,7])) + (0, 6*x^4 + x^3 + x^2 + 2) + + +Methods available on `fmpz_poly` (see upstream docs for details): + + chebyshev_t chebyshev_u coeffs complex_roots content cos_minpoly + cyclotomic deflate derivative discriminant factor factor_squarefree + gcd height_bits hilbert_class_poly inflate is_constant is_cyclotomic + is_gen is_one is_zero leading_coefficient left_shift mul_low + pow_trunc real_roots repr resultant right_shift roots + sqrt str swinnerton_dyer truncate + + +# **nmod** – integers mod wordsize n¶ + +class flint.nmod(*val*, *mod*)¶ +The nmod type represents elements of Z/nZ for word-size n. + + >>> nmod(10,17) * 2 + 3 + + +Methods available on `nmod` (see upstream docs for details): + + is_zero modulus repr sqrt str + + +# **arb** – real numbers¶ + +class flint.arb(*mid=None*, *rad=None*)¶ +Represents a real number \\x\\ by a midpoint \\m\\ and a radius \\r\\ +such that \\x \in \[m \pm r\] = \[m-r, m+r\]\\. The midpoint and radius +are both floating-point numbers. The radius uses a fixed, +implementation-defined precision (30 bits). The precision used for +midpoints is controlled by `ctx.prec` (bits) or equivalently `ctx.dps` +(digits). + +The constructor accepts a midpoint *mid* and a radius *rad*, either of +which defaults to zero if omitted. The arguments can be tuples \\(a, +b)\\ representing exact floating-point data \\a 2^b\\, integers, +floating-point numbers, rational strings, or decimal strings. If the +radius is nonzero, it might be rounded up to a slightly larger value +than the exact value passed by the user. + + >>> arb(10.25) + 10.2500000000000 + >>> print(1 / arb(4)) # exact + 0.250000000000000 + >>> print(1 / arb(3)) # approximate + [0.333333333333333 +/- 3.71e-16] + >>> print(arb("3.0")) + 3.00000000000000 + >>> print(arb("0.1")) + [0.100000000000000 +/- 2.23e-17] + >>> print(arb("1/10")) + [0.100000000000000 +/- 2.23e-17] + >>> print(arb("3.14159 +/- 0.00001")) + [3.1416 +/- 2.01e-5] + >>> ctx.dps = 50 + >>> print(arb("1/3")) + [0.33333333333333333333333333333333333333333333333333 +/- 3.78e-51] + >>> ctx.default() + +Converting to or from decimal results in some loss of accuracy. See +`arb.str()` for details. + + +Methods available on `arb` (see upstream docs for details): + + abs_lower abs_upper acos acosh agm airy + airy_ai airy_ai_zero airy_bi airy_bi_zero asin asinh + atan atan2 atanh backlund_s bell_number bernoulli + bernoulli_poly bessel_i bessel_j bessel_k bessel_y beta_lower + bin bin_uiui bits ceil chebyshev_t chebyshev_u + chi ci const_catalan const_e const_euler const_glaisher + const_khinchin const_log10 const_log2 const_sqrt_pi contains contains_integer + contains_interior cos cos_pi cos_pi_fmpq cosh cot + cot_pi coth coulomb coulomb_f coulomb_g csc + csch digamma ei erf erfc erfcinv + erfi erfinv exp expint expm1 fac + fac_ui fib floor fmpq fmpz fresnel_c + fresnel_s gamma gamma_fmpq gamma_lower gamma_upper gegenbauer_c + gram_point hermite_h hypgeom hypgeom_0f1 hypgeom_1f1 hypgeom_2f1 + hypgeom_u intersection jacobi_p laguerre_l lambertw legendre_p + legendre_p_root legendre_q lgamma li log log1p + log_base lower man_exp max mid mid_rad_10exp + min nan neg neg_inf nonnegative_part overlaps + partitions_p pi polylog pos_inf rad rel_accuracy_bits + rel_one_accuracy_bits repr rgamma rising rising2 rising_fmpq_ui + root rsqrt sec sech sgn shi + si sin sin_cos sin_cos_pi sin_cos_pi_fmpq sin_pi + sin_pi_fmpq sinc sinc_pi sinh sinh_cosh sqrt + str tan tan_pi tanh union unique_fmpz + upper zeta zeta_nzeros + + +# **acb** – complex numbers¶ + +class flint.acb(*real=None*, *imag=None*)¶ +An *acb* represents a complex number by a rectangular enclosure +consisting of *arb* balls for the real and imaginary parts. + + >>> from flint import fmpq + >>> acb(2) + 2.00000000000000 + >>> acb(2+3j) + 2.00000000000000 + 3.00000000000000j + >>> acb("2 +/- 0.001", fmpq(2,3)) + [2.00 +/- 1.01e-3] + [0.666666666666667 +/- 4.82e-16]j + >>> acb(-1) ** 0.25 + [0.707106781186547 +/- 6.14e-16] + [0.707106781186547 +/- 6.15e-16]j + + +Methods available on `acb` (see upstream docs for details): + + abs_lower abs_upper acos acosh agm airy + airy_ai airy_bi arg asin asinh atan + atanh barnes_g bernoulli_poly bessel_i bessel_j bessel_k + bessel_y beta_lower bits chebyshev_t chebyshev_u chi + ci complex_rad conjugate contains contains_integer contains_interior + cos cos_pi cosh cot cot_pi coth + coulomb coulomb_f coulomb_g csc csch csgn + dft digamma dirichlet_eta dirichlet_l ei elliptic_e + elliptic_e_inc elliptic_f elliptic_inv_p elliptic_invariants elliptic_k elliptic_p + elliptic_pi elliptic_pi_inc elliptic_rc elliptic_rd elliptic_rf elliptic_rg + elliptic_rj elliptic_roots elliptic_sigma elliptic_zeta erf erfc + erfi exp exp_pi_i expint expm1 fresnel_c + fresnel_s gamma gamma_lower gamma_upper gegenbauer_c hermite_h + hypgeom hypgeom_0f1 hypgeom_1f1 hypgeom_2f1 hypgeom_u integral + jacobi_p laguerre_l lambertw legendre_p legendre_q lerch_phi + lgamma li log log1p log_barnes_g log_sin_pi + mid modular_delta modular_eta modular_j modular_lambda modular_theta + neg overlaps pi polygamma polylog pow + rad real_abs real_ceil real_floor real_heaviside real_max + real_min real_sgn real_sqrt rel_accuracy_bits rel_one_accuracy_bits repr + rgamma rising rising2 root rsqrt sec + sech sgn shi si sin sin_cos + sin_cos_pi sin_pi sinc sinc_pi sinh sinh_cosh + spherical_y sqrt stieltjes str tan tan_pi + tanh union unique_fmpz zeta zeta_zero zeta_zeros \ No newline at end of file diff --git a/apn/lean/docs/regina/LICENSE b/apn/lean/docs/regina/LICENSE new file mode 100644 index 00000000..1e06c482 --- /dev/null +++ b/apn/lean/docs/regina/LICENSE @@ -0,0 +1,470 @@ + + Regina - Software for low-dimensional topology + Copyright (c) 1999-2023, The Regina development team + + +CITATION: + +If you find Regina useful in your research, please consider citing it as +you would any other paper that you use. A suggested form of reference is: + + Benjamin A. Burton, Ryan Budney, William Pettersson, et al., + "Regina: Software for low-dimensional topology", + http://regina-normal.github.io/, 1999-2023. + + +AUTHORS: + +The primary developers of Regina are: + + Benjamin Burton + Ryan Budney + William Pettersson + +Many others have been of assistance with this project, be it through time, +knowledge, testing or code. Please see the full list of acknowledgements +in the users' handbook. + + +COPYING AND MODIFICATION: + +This program is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2 of the License, or (at your +option) any later version. + +Some of this code comes with additional permissions; see the section +below regarding online distribution. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +A full copy of the GNU General Public License should be included below; +if not, write to the Free Software Foundation, Inc., 51 Franklin St, +Fifth Floor, Boston, MA 02110-1301, USA. + + +ONLINE DISTRIBUTION: + +Regina's own source code comes with the following permissions in +addition to the GNU General Public License: + +As an exception, when this program is distributed through (i) the +App Store by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or +(iii) Google Play by Google Inc., then that store may impose any +digital rights management, device limits and/or redistribution +restrictions that are required by its terms of service. + +Some third-party libraries included in Regina are not granted this +exception, and must be removed from any build that is distributed on +stores that cannot comply with the GNU General Public License (such as +Apple's App Store). See the third-party licenses below for details. + + +SNAPPEA AND SNAPPY: + +Regina includes portions of the SnapPea kernel and its successor SnapPy, +which it uses for some geometric calculations. The SnapPea kernel was +originally written by Jeff Weeks. SnapPy, where this kernel is now maintained, +is primarily developed by Marc Culler, Nathan Dunfield and Matthias Goerner, +with contributions from many people. SnapPy and the corresponding SnapPea +kernel are distributed under the terms of the GNU General Public License, +version 2 or any later version, as published by the Free Software Foundation. + + +NORMALIZ LIBRARY: + +Regina includes a copy of libnormaliz, which it uses to help with the +enumeration of fundamental normal surfaces. Normaliz was written by Winfried +Bruns, Christof Soeger and others. It is distributed under the terms of +the GNU General Public License as published by the Free Software Foundation, +either version 3 of the License, or (at your option) any later version. + + +PYBIND11: + +Regina includes a copy of pybind11, which it uses to generate python bindings +for Regina's native C++ code. The pybind11 library was written by +Wenzel Jakob, and is distributed under a BSD-style license that is shipped +with Regina's source code in the file python/pybind11/LICENSE. + + +PYTHON RLCOMPLETER MODULE: + +Regina includes a modified copy of the Python rlcompleter module, which it +uses for tab completion in the graphical user interface. The original +rlcompleter module was distributed under the Python Software Foundation +License Version 2; the full license and copyright notice are shipped with +Regina's source code in the file python/regina/LICENSE. + + +ORB KERNEL: + +Regina includes snippets of code from Orb, for use in importing and +exporting files in Orb / Casson format. Orb is based on SnapPea +(see above) with additional code written by Damian Heard, who has also +given permission for his code to be distributed under the terms of the +GNU General Public License. + + +SYNTAX HIGHLIGHTING: + +Regina's graphical user interfaces incorporate a modified version of the KDE +syntax-highlighting framework, which they use for highlighting Python scripts. +This framework is distributed under the GNU Library General Public License, +version 2 or any later version, as published by the Free Software Foundation. + + +ICONS: + +Many of Regina's icons are custom-made, and are under the same license as +Regina. Some system icons are taken from the Humanity icon set (licensed +under the GNU General Public License version 2) and the Oxygen icon set +(licensed under the GNU Lesser General Public License version 3 or later). +Regina's die icon is based on an image from openclipart.org, which has been +released into the public domain. + + + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/apn/lean/docs/regina/regina-python.md b/apn/lean/docs/regina/regina-python.md new file mode 100644 index 00000000..bdf556a9 --- /dev/null +++ b/apn/lean/docs/regina/regina-python.md @@ -0,0 +1,948 @@ + + + +## Chapter 9. Python Scripting + +**Table of Contents** + + + + + + + + + + + + + + + + + + + + + + + + + + + +Regina contains inbuilt scripting, which offers you fine control over +Regina's mathematical engine and enables you to automate large amounts +of processing. You can write and run scripts from directly within +Regina, or you can use the separate command-line tool +. + +The user interface will stay in sync with any changes that you make +through a script, which means you can happily modify a data file via +scripts while you have it open. + +All scripts in Regina use the Python programming language +(). The specific Python +version must be chosen at build time. If you download a ready-made +package then the packager has already chosen the Python version for you; +the ready-made packages on the Regina website will always use the +default version of Python on each system where possible. + +### Warning + +Regina's Python interface typically assumes you know what you are doing, +and so the onus is on you to follow the rules. All constraints, +preconditions and so on are thoroughly documented in the . Probably the +easiest way to crash Regina is to bring up a Python console and do +something “illegal” (like gluing together two tetrahedra that belong to +different triangulations). + +## Starting a Python Session + +There are several ways of starting a Python session to work with Regina: + +### Graphical Python Consoles + +You can open a graphical Python console by selecting Tools→Python +Console from the menu (or by pressing the corresponding toolbar button). + +! + +A new console window will open as illustrated below, with an input area +down the bottom (see the red arrow) and a full history of the session in +the main part of the window. You can save this history by selecting +Console→Save Session. + +! + +When you start the Python session, Regina will set some special +variables for you: + +`item` +If you have a packet selected in the tree when you start the Python +session, the variable `item` will refer to this packet (see the figure +above for an example of this). + +Note that, if you later change your selection in the packet tree, the +`item` variable will not change as a result. + +`root` +The variable `root` will refer to the hidden root at the top of your +packet tree (this root is not visible in the user interface, but its +top-level children are). + +You are welcome to use these variables to change packets in your data +file (or even add, remove or rename packets): the graphical user +interface will always stay in sync with any changes that you make via +Python. + +### Command-Line Sessions + +You can run the command-line program + without a +graphical user interface at all. This will use the standard Python +interpreter. Since this is a text-based interface, you can also redirect +input and output in the usual way (using \< and \> in your command +shell). + +! + +macOS users will find **regina-python** inside Regina's application +bundle. See the  +for details. + +Windows users do not have the command-line **regina-python** at all, +though they can still use  and +. + +### Script Packets + +You can create a new  in your data +file. Script packets allow you to save Python scripts along with your +data, and they give your scripts easy access to the packets inside your +file. + +! + +When you open a script packet, you will see your Python code in the +lower part of the script editor, and a table of variables up the top. + +! + +You can add your own variables to this table, and set them to arbitrary +packets within your data file. Regina will always set these variables to +the corresponding packets before running your script. + +! + +At the top of the script editor you will find buttons to compile and run +your script. Compiling is optional: it merely gives you a chance to spot +syntax errors as you go. When you press Run, Regina will run your script +in a new graphical Python console. The console will be left open in case +you wish to experiment further. + +! + +Again, you are welcome to change packets in your data file via scripts +(or even add, remove or rename packets): the graphical user interface +will always stay in sync with any changes that your scripts make. + +## Accessing Regina from Python + +All of Regina's objects, classes and methods belong to the module called +*`regina`*. For instance, the main 3-manifold triangulation class is +`regina.Triangulation3`, the main knot/link class is `regina.Link`, and +the main routine to read a data file is `regina.open`. + +### Automatic Imports + +Whenever Regina gives you access to Python (either through a , a , or a +), it will +automatically import the *`regina`* module (i.e., “`import regina`”), +and it will import all of Regina's objects, classes and methods into the +current namespace (i.e., “`from regina import *`”). As a single +exception, it will *not* import `regina.open`, so as to not hide +Python's own `open()` function. + +This means, for instance, that you can create a new triangulation by +just calling `Triangulation3()`, but to read a data file you should +still call `regina.open(filename)`. For command-line sessions, if you +wish to avoid the heavy-handed “`from regina import *`”, you can pass +the option `--noautoimport` to **regina-python** (in which case you will +need to use fully qualified names such as `regina.Triangulation3()`). + +## API Documentation + +Regina includes a complete API reference for its calculation engine, +which describes in detail the objects, classes and methods that are +available through Python. To read this documentation, you can: + +- read the locally installed documentation by selecting Help→Python API + Reference; +- read it online through the ; +- read it inline from  + (see below). + +Be aware that this API documentation is primarily written for C++ (the +main language that Regina is written in). This means: + +- The documentation uses C++ notation and C++ types, though these are + all translated in the natural way to Python (e.g., `std::string` + becomes a Python string, and `std::vector` becomes a Python list). +- Some functions differ in how they are called from C++ versus Python. + In such cases you will see the C++ description, but there will also be + a “Python” paragraph explaining how things differ in Python. + +There are more issues that Python users should be aware of; please do +read the  +that outlines the main differences. + +### Inline Documentation + +Since version; 7.2, Regina now provides Python docstrings for all of its +classes and functions. This means that you can get help directly from +the Python prompt, as illustrated below. + +Be aware, however, that this documentation is extracted automatically +from the hand-written C++ API documentation discussed above. Although +great attention has been paid to making this extraction as useful and +natural as possible, it is still automated. Therefore you will find: + +- The documentation still uses some C++ terminology (e.g., + `std::string`, pointers and references, move semantics, etc.). +- Function arguments are often not named in the synopsis at the + beginning of the docstring (you will see them called `arg0`, `arg1`, + etc.). However, they *are* named in the detailed descriptions of the + arguments that follow. +- Some functions differ in how they are called from C++ versus Python + (e.g., `Tetrahedron3.face()`, or `Link.rewrite()`). In these cases, + the detailed hand-written argument descriptions will follow the C++ + variant, but the initial synopsis will be written for Python. For + clarity, here the arguments in the Python synopsis *will* be named. + Look also for a “Python” paragraph that explains exactly how the C++ + and Python versions differ. +- Some parts of the documentation are not accessible at all through + Python, since they do not correspond to entities that hold docstrings + (e.g., class constants such as `Perm4::nPerms`, or standalone pages + such as the discussion on Seifert fibred space notation). + +Ultimately, *it is the C++ documentation that is authoritative*, not the +inline Python documentation. Again, remember that you can always . + +An example of docstrings for member functions: + +``` programlisting +>>> help(NormalSurface.components) +Help on instancemethod in module regina.engine: + +components(...) + components(self: regina.NormalSurface) -> List[regina.NormalSurface] + + Splits this surface into connected components. + + A list of connected components will be returned. These components will + always be encoded using standard (tri-quad or tri-quad-oct) + coordinates, regardless of the internal vector encoding that is used + by this surface. + + Precondition: + This normal surface is embedded (not singular or immersed). + + Precondition: + This normal surface is compact (has finitely many discs). + + .. warning:: + This routine explicitly builds the normal discs, and so may run + out of memory if the normal coordinates are extremely large. + + Returns: + the list of connected components. +``` + +An example of docstrings for classes: + +``` programlisting +>>> help(Crossing) +Help on class Crossing in module regina.engine: + +class Crossing(pybind11_builtins.pybind11_object) + | Represents a single crossing in a link diagram. The two strands of the + | link that run over and under the crossing respectively can be accessed + | through routines such as over(), under(), upper(), lower(), and + | strand(). + | + | Each crossing has a sign, which is either positive (denoted by +1) or + | negative (denoted by -1): + | + | * In a positive crossing, the upper strand passes over the lower + | strand from left to right: + | + | ``` + | -----\ /-----> + | \ + | -----/ \-----> + | ``` + | + | * In a negative crossing, the upper strand passes over the lower + | strand from right to left: + | + | ``` + | -----\ /-----> + | / + | -----/ \-----> + | ``` + | + | If a link has *n* crossings, then these are numbered 0,...,*n*-1. The + | number assigned to this crossing can be accessed by calling index(). + | Note that crossings in a link may be reindexed when other crossings + | are added or removed - if you wish to track a particular crossing + | through such operations then you should use a pointer to the relevant + | Crossing object instead. + | + | ... (documentation continues) ... +``` + +## Talking with SnapPy + +Since Regina 4.95, a default installation of Regina can talk directly +with a default installation of SnapPy on many platforms. This includes +macOS 10.7 or greater (if you installed the SnapPy app bundle in the +usual `Applications` folder), and GNU/Linux (if your SnapPy uses the +default system Python installation). + +Simply type **`import snappy`** from within any of Regina's Python +environments. To send information back and forth between Regina and +SnapPy: + +- Regina's triangulation classes `Triangulation3` and + `SnapPeaTriangulation` both have a `snapPea()` function, which gives a + string that you can pass to SnapPy's `Manifold` constructor. + +- SnapPy's `Manifold` class has a `_to_string()` function, which gives a + string that you can pass to Regina's `Triangulation3` or + `SnapPeaTriangulation` constructor. + +Regarding fillings and peripheral curves: Regina does not store fillings +or peripheral curves for its own native , +as represented by the `Triangulation3` class. However, it does store +fillings and peripheral curves for its hybrid , as +represented by the `SnapPeaTriangulation` class. The trade-off is that +the native `Triangulation3` class offers Regina's full fine-grained +control over the triangulation, whereas the hybrid +`SnapPeaTriangulation` class has a more limited (largely read-only) +interface. + +- When sending data from Regina to SnapPy, if your triangulation is of + the class `Triangulation3`, then `Triangulation3.snapPea()` will + create a SnapPy manifold in which all fillings and peripheral curves + are marked as unknown. If your triangulation is of the class + `SnapPeaTriangulation`, and if you already have fillings and + peripheral curves stored on each cusp, then + `SnapPeaTriangulation.snapPea()` will create a SnapPy manifold that + preserves these. + +- Conversely, when sending data from SnapPy to Regina, you can choose to + instantiate a triangulation using either the `Triangulation3` class or + the `SnapPeaTriangulation` class. If you use the `Triangulation3` + class then all fillings and peripheral curves will be lost. If you use + the `SnapPeaTriangulation` class then fillings and peripheral curves + will be preserved (but your interface will be more restricted). + +If you wish to send the complement of a native Regina `Link` to SnapPy, +you can pass your link directly to the `SnapPeaTriangulation` +constructor, which will preserve the peripheral curves from the link +diagram; then you can pass this to SnapPy via +`SnapPeaTriangulation.snapPea()` as above. + +Regarding the interface: the `SnapPeaTriangulation` class inherits from +`Triangulation3`, and so you can use it anywhere that a read-only +triangulation is expected (in particular, you can use it for enumerating +vertex normal surfaces or angle structures). However, because +`SnapPeaTriangulation` must maintain two synchronised copies of the +triangulation (Regina's and SnapPea's), it is essentially read-only: any +attempt to modify the triangulation using Regina's native routines +(e.g., `pachner()` or `barycentricSubdivision()`) will cause the SnapPea +triangulation to delete itself and become a “null triangulation” +instead. + +### Warning + +At present, SnapPy (version 2.0.3) is not compatible with multiple +Python interpreters. If you import SnapPy into more than one Python +console in the graphical user interface, SnapPy may stop working. See + +for details. + +The following Python session illustrates several of the concepts +discussed above. + +``` programlisting +bab@ember:~$ regina-python +Regina 7.2 +Software for low-dimensional topology +Copyright (c) 1999-2022, The Regina development team +>>> import snappy +>>> m = snappy.Manifold('m001') +>>> t = SnapPeaTriangulation(m._to_string()) +>>> print t.detail() +Size of the skeleton: + Tetrahedra: 2 + Triangles: 4 + Edges: 2 + Vertices: 1 + +Tetrahedron gluing: + Tet | glued to: (012) (013) (023) (123) + -----+------------------------------------------------------- + 0 | 1 (103) 1 (320) 1 (210) 1 (132) + 1 | 0 (320) 0 (102) 0 (310) 0 (132) + +Vertices: + Tet | vertex: 0 1 2 3 + -----+-------------------------- + 0 | 0 0 0 0 + 1 | 0 0 0 0 + +Edges: + Tet | edge: 01 02 03 12 13 23 + -----+-------------------------------- + 0 | 0 1 1 1 1 0 + 1 | 0 1 1 1 1 0 + +Triangles: + Tet | face: 012 013 023 123 + -----+------------------------ + 0 | 0 1 2 3 + 1 | 2 0 1 3 + +Tetrahedron shapes: + 0: ( -1.60812e-16, 1 ) + 1: ( -1.60812e-16, 1 ) + +Cusps: + 0: Vertex 0, complete + +>>> print t.hasStrictAngleStructure() +True +>>> print AngleStructures(t).detail() +4 vertex angle structures (no restrictions): +0 1 0 ; 1 0 0 +0 0 1 ; 1 0 0 +1 0 0 ; 0 1 0 +1 0 0 ; 0 0 1 + +>>> t2 = Example3.figureEight() +>>> m2 = snappy.Manifold(t2.snapPea()) +>>> print m2.volume() +2.02988321282 +>>> + +``` + +## Sample Python Sessions + +Several sample Python sessions are reproduced below. Each session was +started by running **`regina-python`** from the command line. + +### Working with a triangulation + +``` programlisting +example$ regina-python +Regina 7.0 +Software for low-dimensional topology +Copyright (c) 1999-2021, The Regina development team +>>> ################################ +>>> # +>>> # Sample Python Script +>>> # +>>> # Illustrates different queries and actions on a 3-manifold triangulation +>>> # and its normal surfaces. +>>> # +>>> # See the file "triangulation.session" for the results of running this +>>> # script. +>>> # +>>> ################################ +>>> +>>> # Create a new (3,4,7) layered solid torus. This is a 3-tetrahedron +>>> # triangulation of a solid torus. +>>> t = Example3.lst(3, 4) +>>> print(t) +Bounded orientable 3-D triangulation, f = ( 1 5 7 3 ) +>>> +>>> # Print the full skeleton of the triangulation. +>>> print(t.detail()) +Size of the skeleton: + Tetrahedra: 3 + Triangles: 7 + Edges: 5 + Vertices: 1 + +Tetrahedron gluing: + Tet | glued to: (012) (013) (023) (123) + -----+------------------------------------------------------- + 0 | boundary boundary 1 (012) 1 (130) + 1 | 0 (023) 0 (312) 2 (013) 2 (120) + 2 | 1 (312) 1 (023) 2 (312) 2 (230) + +Vertices: + Tet | vertex: 0 1 2 3 + -----+-------------------------- + 0 | 0 0 0 0 + 1 | 0 0 0 0 + 2 | 0 0 0 0 + +Edges: + Tet | edge: 01 02 03 12 13 23 + -----+-------------------------------- + 0 | 0 1 2 2 1 3 + 1 | 1 2 3 3 2 4 + 2 | 2 4 3 3 4 3 + +Triangles: + Tet | face: 012 013 023 123 + -----+------------------------ + 0 | 0 1 2 3 + 1 | 2 3 4 5 + 2 | 5 4 6 6 + +>>> +>>> # Calculate some algebraic properties of the triangulation. +>>> print(t.homology()) +Z +>>> print(t.homologyBdry()) +2 Z +>>> +>>> # Test for 0-efficiency, which asks Regina to search for certain types +>>> # of normal surfaces. +>>> print(t.isZeroEfficient()) +False +>>> +>>> # Make our own list of vertex normal surfaces in standard coordinates. +>>> surfaces = NormalSurfaces(t, NormalCoords.Standard) +>>> +>>> # Print the full list of vertex normal surfaces. +>>> print(surfaces.detail()) +Embedded, vertex surfaces +Coordinates: Standard normal (tri-quad) +Number of surfaces is 9 +1 1 1 1 ; 0 0 0 || 1 1 0 0 ; 1 0 0 || 0 0 0 0 ; 0 2 0 +0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0 +0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0 +0 0 0 0 ; 0 0 2 || 0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 +1 1 0 0 ; 0 0 1 || 1 1 0 0 ; 0 0 0 || 0 0 0 0 ; 0 1 0 +3 3 0 0 ; 0 0 1 || 1 1 0 0 ; 0 0 2 || 1 1 0 0 ; 0 0 1 +0 0 1 1 ; 1 0 0 || 1 1 0 0 ; 1 0 0 || 0 0 0 0 ; 0 2 0 +0 0 0 0 ; 0 1 0 || 0 0 0 0 ; 1 0 0 || 0 0 0 0 ; 0 1 0 +1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0 + +>>> +>>> # Print the Euler characteristic and orientability of each surface. +>>> for s in surfaces: +... print("Chi =", s.eulerChar(), "; Or =", s.isOrientable()) +... +Chi = -1 ; Or = True +Chi = 0 ; Or = True +Chi = 0 ; Or = True +Chi = 0 ; Or = True +Chi = 0 ; Or = False +Chi = 1 ; Or = True +Chi = -2 ; Or = True +Chi = -1 ; Or = False +Chi = 1 ; Or = True +>>> +>>> # List all surfaces with more than one quad in the first tetrahedron. +>>> for s in surfaces: +... if s.quads(0,0) + s.quads(0,1) + s.quads(0,2) > 1: +... print(s) +... +0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0 +0 0 0 0 ; 0 0 2 || 0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 +>>> +``` + +### Working with a packet tree + +``` programlisting +example$ regina-python +Regina 7.0 +Software for low-dimensional topology +Copyright (c) 1999-2021, The Regina development team +>>> ################################ +>>> # +>>> # Sample Python Script +>>> # +>>> # Illustrates the traversal and manipulation of an entire packet tree. +>>> # +>>> # See the file "tree.session" for the results of running this script. +>>> # +>>> ################################ +>>> +>>> # Recreate the original SnapPea census of cusped hyperbolic manifolds +>>> # triangulated by at most 5 tetrahedra. +>>> # +>>> # Since we are building a packet tree, we need to use PacketOfTriangulation3, +>>> # not the plain type Triangulation3 (which is not a packet type). +>>> census = Container() +>>> for i in range(415): +... mfd = SnapPeaCensusManifold(SnapPeaCensusManifold.SEC_5, i) +... census.append(make_packet(mfd.construct(), mfd.name())) +... +>>> # The triangulations are now all children of the "census" container. +>>> # Remove all triangulations with more than two tetrahedra. +>>> # +>>> # Since we are deleting children, we step through the children manually +>>> # instead of just iterating over children(). +>>> tri = census.firstChild() +>>> while tri != None: +... next = tri.nextSibling() +... if tri.size() > 2: +... tri.makeOrphan() +... tri = next +... +>>> # Print the homology of each remaining triangulation. +>>> # This time we are not adding or removing children, so we can just iterate. +>>> for tri in census.children(): +... print(tri.label() + ":", tri.homology()) +... +Gieseking manifold: Z +SnapPea m001: Z + Z_2 +SnapPea m002: Z + Z_2 +SnapPea m003: Z + Z_5 +Figure eight knot complement: Z +>>> +``` + +### Reporting progress of long operations + +``` programlisting +example$ regina-python +Regina 7.0 +Software for low-dimensional topology +Copyright (c) 1999-2021, The Regina development team +>>> ################################ +>>> # +>>> # Sample Python Script +>>> # +>>> # Illustrates progress reporting during long operations. +>>> # +>>> # See the file "progress.session" for the results of running this script. +>>> # +>>> ################################ +>>> +>>> import threading +>>> import time +>>> +>>> # Create an 18-tetrahedron triangulation of a knot complement with real +>>> # boundary faces (not an ideal vertex). The knot is L106003 from the +>>> # knot/link census. We used Regina to truncate the ideal vertex, and +>>> # then copied the isomorphism signature so that we can reconstruct the +>>> # triangulation here. +>>> sig = 'sfLfvQvwwMQQQccjghjkmqlonrnrqpqrnsnksaisnrobocksks' +>>> tri = Triangulation3(sig) +>>> print(tri) +Bounded orientable 3-D triangulation, f = ( 1 20 37 18 ) +>>> +>>> # Create a progress tracker to use during the normal surface enumeration. +>>> # This will report the state of progress while the enumeration runs in +>>> # the background. +>>> tracker = ProgressTracker() +>>> +>>> # Start the normal surface enumeration in a new thread. +>>> surfaces = None +>>> def run(): +... global surfaces, tracker +... surfaces = NormalSurfaces(tri, NormalCoords.Standard, NormalList.Vertex, +... NormalAlg.Default, tracker) +... +>>> thread = threading.Thread(target = run) +>>> thread.start() +>>> +>>> # At this point the enumeration is up and running. +>>> # Output a progress report every quarter-second until it finishes. +>>> while not tracker.isFinished(): +... print('Progress:', tracker.percent(), '%') +... time.sleep(0.25) +... +Progress: 0.17578125 % +Progress: 54.20654296875 % +Progress: 91.80555555555556 % +>>> +>>> # The surface enumeration is now complete. +>>> thread.join() +>>> print(surfaces) +2319 embedded, vertex surfaces (Standard normal (tri-quad)) +>>> +``` + +## Name + +regina-python — Regina's command-line Python interface + +## Synopsis + +**regina-python** \[\[`-q, --quiet`\] \| \[`-v, --verbose`\]\] +\[`-n, --nolibs`\] \[`-a, --noautoimport`\] + +**regina-python** \[\[`-q, --quiet`\] \| \[`-v, --verbose`\]\] +\[`-n, --nolibs`\] \[`-a, --noautoimport`\] \[`-i, --interactive`\] +{*`script`*} \[*`script-args`*\] + +## Description + +Regina is a software package for 3-manifold and 4-manifold topologists, +with a focus on triangulations, knots and links, normal surfaces, and +angle structures. For 3-manifolds, it includes high-level tasks such as +3-sphere and unknot recognition, connected sum decomposition and +Hakenness testing, comes with a rich database of census manifolds, and +incorporates the SnapPea kernel for working with hyperbolic manifolds. +For 4-manifolds, it offers a range of combinatorial and algebraic tools, +plus support for normal hypersurfaces. For knots and links, Regina can +perform combinatorial manipulation, compute knot polynomials, and work +with several import/export formats. Regina comes with a full graphical +user interface, as well as Python bindings and a low-level C++ +programming interface. + +This command starts an interactive Python session for Regina. This will +be a command-line Python session, with direct text input/output and no +graphical user interface. All of the objects, clases and methods from +Regina's mathematical engine will be made available through the module +*`regina`*, which will be imported on startup (effectively running +`import regina`). Moreover, unless the option `--noautoimport` is +passed, all of Regina's objects, classes and methods will be imported +directly into the current namespace (effectively running +`from regina import *`). + +Instead of starting an interactive Python session, you can pass a Python +script (with arguments if desired). In this case Regina will run the +script (after first importing the *`regina`* module). If you pass +`--interactive`, Regina will leave you at a Python prompt once the +script finishes; otherwise it will exit Python and return you to the +command line. + +## Options + +`-q`, `--quiet` +Start in quiet mode. No output will be produced except for serious +errors. In particular, warnings will be suppressed. + +This is equivalent to setting the environment variable +*`REGINA_VERBOSITY`*=`0`. + +`-v`, `--verbose` +Start in verbose mode. Additional diagnostic information will be output. + +This is equivalent to setting the environment variable +*`REGINA_VERBOSITY`*=`2`. + +`-a`, `--noautoimport` +Still import the *`regina`* module, but do not automatically import all +of Regina's objects, classes and methods into the current namespace +(that is, do not run `from regina import *`). This means that (for +example) the main 3-manifold triangulation class must be accessed as +`regina.Triangulation3`, not just `Triangulation3`. + +`-i`, `--interactive` +Run the script in interactive mode. After executing the given script, +Regina will leave you in the Python interpreter to run your own +additional commands. + +This option is only available when a script is passed. If no script is +passed, **regina-python** will always start in interactive mode. + +## Environment Variables + +The following environment variables influence the behaviour of this +program. Most variables can also be set in the local configuration file +`~/.regina-python` using a line of the form *`option`*=*`value`*; +exceptions are noted below. Environment variables take precedence over +values in the configuration file. + +*`REGINA_VERBOSITY`* +Specifies how much output should be generated. Recognised values are: + +`0` +Display errors only; this is equivalent to passing the option `--quiet`. + +`1` +Display errors and warnings; this is the default. + +`2` +Display errors, warnings and diagnostic output; this is equivalent to +passing the option `--verbose`. + +*`REGINA_PYTHON`* +The command used to start the Python interpreter. + +In general you should use the same version of Python that Regina was +built against; otherwise Python might not be able to load the *`regina`* +module. + +Normally you should not need to set this option yourself. By default, +Regina will use the same Python installation that it was built against. + +*`REGINA_PYLIBDIR`* +The directory containing the Python module *`regina`*. + +If you have installed Regina's Python module in a standard Python +location (i.e., Python can import it directly without extending +`sys.path`), then *`REGINA_PYLIBDIR`* should be left empty or undefined. + +Normally you should not need to set this option yourself. This program +should know how to find Regina's Python module in standard situations, +which include fixed filesystem installations (e.g., GNU/Linux and +Windows), relocatable app bundles (e.g., macOS), and running directly +from the source tree. + +*`REGINA_HOME`* +The directory beneath which Regina's data files are installed. In +particular, Regina's census lookup routines will look for the census +databases in the subdirectory *`$REGINA_HOME`*`/data/census/`. + +This option can only be set from the environment: it cannot be set in +the configuration file `~/.regina-python`. + +Normally you should not need to set this option yourself. This program +should know how to find its data files in standard situations, which +include fixed filesystem installations (e.g., GNU/Linux and Windows), +relocatable app bundles (e.g., macOS), and running directly from the +source tree. + +## macOS Users + +If you downloaded a drag-and-drop app bundle, this utility is shipped +inside it. If you dragged Regina to the main Applications folder, you +can run it as `/Applications/Regina.app/Contents/MacOS/regina-python`. + +## Windows Users + +The command **regina-python** is not available under Windows. However, +you can still use Python scripting in Regina's graphical user interface, +by opening a graphical Python console or using script packets. + +## See Also + +. + +Regina comes with thorough API documentation, which describes in detail +all of the objects, classes and methods that Regina makes available to +Python. You can access this documentation via Help→Python API Reference +in the graphical user interface, or read it online at +. + +## Author + +Many people have been involved in the development of Regina; see the + for a full list +of credits. + +-  +-  + + \|  + +regina::Census Class Reference + + + +A utility class used to search for triangulations across one or more +3-manifold census databases.  + +`#include ` + +## Detailed Description + +A utility class used to search for triangulations across one or more +3-manifold census databases. + +This class consists of static routines only. The main entry point (and +typically the only way that you would use this class) is via the various +static + +routines. + +Warning +This class is not thread-safe, in that it performs some global +initialisation the first time one of the + +functions is called. If you need thread-safety, you can always call + +with an empty string when initialising your program, and ensure this has +finished before you allow any subsequent "normal" calls to + +from other threads. + +## Member Function Documentation + +## lookup() \[1/2\] + +Searches for the given triangulation through all of Regina's in-built +census databases. + +For this routine you specify the triangulation by giving its isomorphism +signature, as returned by +. +This is faster than the variant , +since Regina's census databases store isomorphism signatures internally. +If you do not already know the isomorphism signature, it is fine to just +call  +instead. + +Note that there may be many hits (possibly from multiple databases, and +in some cases possibly even within the same database). Therefore a +*list* of hits will be returned, which you can iterate through the +individual matches. Even if there are no matches at all, a list will +still be returned; you can call empty() on this list to test whether any +matches were found. + +This routine is fast: it first computes the isomorphism signature of the +triangulation, and then performs a logarithmic-time lookup in each +database (here "logarithmic" means logarithmic in the size of the +database). + +Parameters + +  + +Returns +a list of all database matches. + +## lookup() \[2/2\] + +Searches for the given triangulation through all of Regina's in-built +census databases. + +Internally, the census databases store isomorphism signatures as opposed +to fully fleshed-out triangulations. If you already have the isomorphism +signature of the triangulation, then you can call the variant + +instead, which will be faster since it avoids some extra overhead. + +Note that there may be many hits (possibly from multiple databases, and +in some cases possibly even within the same database). Therefore a +*list* of hits will be returned, which you can iterate through the +individual matches. Even if there are no matches at all, a list will +still be returned; you can call empty() on this list to test whether any +matches were found. + +This routine is fast: it first computes the isomorphism signature of the +triangulation, and then performs a logarithmic-time lookup in each +database (here "logarithmic" means logarithmic in the size of the +database). + +Parameters + +  + +Returns +a list of all database matches. + +------------------------------------------------------------------------ + +The documentation for this class was generated from the following file: + +- census/ + +------------------------------------------------------------------------ + +Copyright © 1999–2025, The Regina development team + diff --git a/apn/lean/docs/snappy/LICENSE b/apn/lean/docs/snappy/LICENSE new file mode 100644 index 00000000..a825130a --- /dev/null +++ b/apn/lean/docs/snappy/LICENSE @@ -0,0 +1,351 @@ +License +======= + +Copyright 2007-present by Marc Culler, Nathan Dunfield, Matthias +Goerner, Jeff Weeks and others. + +This code is released under the `GNU General Public License, version 2 +`_ or (at your option) any +later version as published by the Free Software Foundation. + +---------------------------------------------------------------------- + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/apn/lean/docs/snappy/snappy.md b/apn/lean/docs/snappy/snappy.md new file mode 100644 index 00000000..6c4709ec --- /dev/null +++ b/apn/lean/docs/snappy/snappy.md @@ -0,0 +1,1238 @@ + + +# Tutorial + +The easiest way to learn to use SnapPy is to watch the screencasts +available on YouTube: + +- Intro and quickstart: an 11 minute video with the basics: Part + I and Part + II. + +- An hour-long demo Practical computation with hyperbolic + 3-manifolds, recorded at the Thurston + Memorial Conference. + +- The SnapPy 2.0 new feature demo. + +- SnapPy, SageMath, and Docker are + friends with + associated materials (4 pages), including + homework. + +- Notes, problem sheets, and + references from the LMS-CMI + Research School in Warwick in 2017. + +- Another hour-long demo Practical computations with hyperbolic + 3-manifolds given + at ICERM in 2019. + +The **key** thing to remember when using the SnapPy command shell window +is that you can explore objects using introspection and tab-completion: + + In [1]: Manifold? + ...instructions for creating a manifold... + +So now we create a manifold: + + In [2]: M = Manifold("m004") + +But what can we do with it? + + In [3]: M. + ...list of methods... + +What does the “cover” method do? + + In [4]: M.cover? + ...description of cover method.. + +# The snappy module and its classes + +SnapPy is centered around a Python interface for SnapPea called +“snappy”, and this is what you’re interacting with in the main “SnapPy +command shell” window. The main class is Manifold, which is an ideal +triangulation of the interior of a compact 3-manifold with torus +boundary, where each tetrahedron has been assigned the geometry of an +ideal tetrahedron in hyperbolic 3-space. A Dehn-filling can be specified +for each boundary component, allowing the description of closed +3-manifolds and some orbifolds. The class Manifold is derived from the +simpler Triangulation class which lacks any geometric structure. There +are also some additional classes for things like fundamental groups, +Dirichlet domains, etc. Snappy comes with a large library of +3-manifolds, some of which are grouped together in censuses. + +- Manifold: the main class + - `Manifold` +- ManifoldHP: High-precision variant + - FAQ +- Triangulation + - `Triangulation` +- Additional Classes + - AbelianGroup + - FundamentalGroup + - SymmetryGroup + - DirichletDomain + - CuspNeighborhood +- Census manifolds + - `OrientableCuspedCensus` + - `OrientableClosedCensus` + - `CensusKnots` + - `LinkExteriors` + - `HTLinkExteriors` + - `RibbonLinks` + - `NonorientableCuspedCensus` + - `NonorientableClosedCensus` + - Censuses of Platonic manifolds + - `ManifoldTable` + - `AlternatingKnotExteriors` + - `NonalternatingKnotExteriors` + +# Manifold: the main class + +*class *snappy.Manifold +A Manifold is a +`Triangulation` +together with a geometric structure. That is, a Manifold is an ideal +triangulation of the interior of a compact 3-manifold with torus and +Klein-bottle boundary components, where each tetrahedron has been +assigned the geometry of an ideal tetrahedron in hyperbolic 3-space. A +Dehn-filling can be specified for each boundary component, allowing the +description of closed 3-manifolds, some orbifolds and cone 3-manifolds. +Here’s a quick example: + + >>> M = Manifold('9_42') + >>> M.volume() + 4.05686022 + >>> M.cusp_info('shape') + [-4.278936315 + 1.95728679*I] + +This is an example for running SnapPy inside Sage: + + sage: import snappy + sage: M = snappy.Manifold('m125(1,2)(4,5)') + sage: M.is_orientable() + True + +An alternative way of running SnapPy inside Sage: + + sage: from snappy import * + sage: M = Manifold('m123') + sage: M.num_cusps() + 1 + +A Manifold can be specified in a number of ways, e.g. + +- Manifold(‘9_42’) : The complement of the knot 9_42 in S^3. + +- Manifold(‘m125(1,2)(4,5)’) : The SnapPea census manifold m125 where + the first cusp has Dehn filling (1,2) and the second cusp has filling + (4,5). + +- Manifold() : Opens a link editor window where can you specify a link + complement. + +In general, the specification can be from among the below, with +information on Dehn fillings added. + +- SnapPea cusped census manifolds: e.g. ‘m123’, ‘s123’, ‘v123’. + +- Link complements: + + > - Rolfsen’s table: e.g. ‘4_1’, ‘04_1’, ‘5^2_6’, ‘6_4^7’, ‘L20935’, + > ‘l104001’. + > + > - Hoste-Thistlethwaite Knotscape table: e.g. ‘11a17’ or ‘12n345’ + > + > - Callahan-Dean-Weeks-Champanerkar-Kofman-Patterson knots: e.g. + > ‘K6_21’. + > + > - Dowker-Thistlethwaite code: e.g. ‘DT:\[(6,8,2,4)\]’ + +- Once-punctured torus bundles: e.g. ‘b++LLR’, ‘b+-llR’, ‘bo-RRL’, + ‘bn+LRLR’ + +- Fibered manifold associated to a braid: ‘Braid\[1,2,-3,4\]’ + + Here, the braid is thought of as a mapping class of the punctured + disc, and this manifold is the corresponding mapping torus. If you + want the braid closure, do (1,0) filling of the last cusp. + +- From mapping class group data using Twister: + + ‘Bundle(S\_{1,1}, \[a0, B1\])’ or ‘Splitting(S\_{1,0}, \[b1, A0\], + \[a0,B1\])’ + + See the help for the ‘twister’ module for more. + +- A SnapPea triangulation or link projection file: ‘filename’ + + The file will be loaded if found in the current directory or the path + given by the shell variable `SNAPPEA_MANIFOLD_DIRECTORY`. See + `Manifold.save()` for + details. + +- A string containing the contents of a SnapPea triangulation or link + projection file. + +chern_simons(*accuracy=False*) +Returns the Chern-Simons invariant of the manifold (normalized by +dividing it by \\2 \pi^2\\), if it is known. + + >>> M = Manifold('m015') + >>> M.chern_simons() + -0.15320413 + +The return value has an extra attribute, accuracy, which is the number +of digits of accuracy as *estimated* by SnapPea. + + >>> cs, accuracy = M.chern_simons(accuracy = True) + >>> accuracy in (8, 9, 56, 57) # Low and High precision + True + +By default, when the manifold has at least one cusp, Zickert’s algorithm +is used; when the manifold is closed we use SnapPea’s original +algorithm, which is based on Meyerhoff-Hodgson-Neumann. + +Note: When computing the Chern-Simons invariant of a closed manifold, +one must sometimes compute it first for the unfilled manifold so as to +initialize SnapPea’s internals. For instance, + + >>> M = Manifold('5_2') + >>> M.chern_simons() + -0.15320413 + >>> M.dehn_fill( (1,2) ) + >>> M.chern_simons() + 0.07731787 + +works, but will fail with +`ValueError:`` ``The`` ``Chern-Simons`` ``invariant`` ``isn't`` ``currently`` ``known.` +if the first call to chern_simons is not made. + +complex_volume(*verified_modulo_2_torsion=False*, *bits_prec=None*) +Returns the complex volume modulo \\i \pi^2\\ which is given by + +\\\text{vol} + i \text{CS}\\ + +where \\\text{CS}\\ is the (unnormalized) Chern-Simons invariant. + + >>> M = Manifold('5_2') + >>> M.complex_volume() + 2.82812209 - 3.02412838*I + +Note that +`chern_simons` +normalizes the Chern-Simons invariant by dividing it by \\2 \pi^2 = +19.7392...\\ + + >>> M.chern_simons() + -0.153204133297152 + +More examples: + + >>> M.dehn_fill((1,2)) + >>> M.complex_volume() + 2.22671790 + 1.52619361*I + >>> M = Manifold("3_1") # A non-hyperbolic example. + >>> cvol = M.complex_volume() + >>> cvol.real() + 0 + >>> cvol.imag() + -1.64493407 + +If no cusp is filled or there is only one cusped (filled or unfilled), +the complex volume can be verified up to multiples of \\i \pi^2 /2\\ by +passing `verified_modulo_2_torsion`` ``=`` ``True` when inside SageMath. +Higher precision can be requested with `bits_prec`: + + sage: M = Manifold("m015") + sage: M.complex_volume(verified_modulo_2_torsion=True, bits_prec = 93) # doctest: +NUMERIC21 + 2.828122088330783162764? + 1.910673824035377649698?*I + sage: M = Manifold("m015(3,4)") + sage: M.complex_volume(verified_modulo_2_torsion=True) # doctest: +NUMERIC6 + 2.625051576? - 0.537092383?*I + +cover(*permutation_rep*) → snappy.Manifold +Returns a `Manifold` representing +the finite cover specified by a transitive permutation representation. +The representation is specified by a list of permutations, one for each +generator of the simplified presentation of the fundamental group. Each +permutation is specified as a list `P` such such that +`set(P)`` ``==`` ``set(range(d))` where `d` is the degree of the cover. + + >>> M = Manifold('m004') + >>> N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]]) + >>> abs(N0.volume()/M.volume() - 5) < 0.0000000001 + True + +If within SageMath, the permutations can also be of type +`PermutationGroupElement`, in which case they act on the set +`range(1,`` ``d`` ``+`` ``1)`. Or, you can specify a GAP or Magma +subgroup of the fundamental group. Some examples: + + sage: M = Manifold('m004') + +The basic method: + + sage: N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]]) + +From a Gap subgroup: + + sage: G = gap(M.fundamental_group()) + sage: H = G.LowIndexSubgroupsFpGroup(5)[9] + sage: N1 = M.cover(H) + sage: N0 == N1 + True + +Or a homomorphism to a permutation group: + + sage: f = G.GQuotients(PSL(2,7))[1] + sage: N2 = M.cover(f) + sage: N2.volume()/M.volume() # doctest: +NUMERIC9 + 8.00000000 + +Or maybe we want larger cover coming from the kernel of this: + + sage: N3 = M.cover(f.Kernel()) + sage: N3.volume()/M.volume() # doctest: +NUMERIC9 + 168.00000000 + +Check the homology against what Gap computes directly: + + sage: N3.homology().betti_number() + 32 + sage: len([ x for x in f.Kernel().AbelianInvariants().sage() if x == 0]) + 32 + +We can do the same for Magma: + + sage: G = magma(M.fundamental_group()) #doctest: +SKIP + sage: Q, f = G.pQuotient(5, 1, nvals = 2) #doctest: +SKIP + sage: M.cover(f.Kernel()).volume() #doctest: +SKIP + 10.14941606 + sage: h = G.SimpleQuotients(1, 11, 2, 10000)[1,1] #doctest: +SKIP + sage: N4 = M.cover(h) #doctest: +SKIP + sage: N2 == N4 #doctest: +SKIP + True + +cover_info() +If this is a manifold or triangulation which was constructed as a +covering space, return a dictionary describing the cover. Otherwise +return 0. The dictionary keys are ‘base’, ‘type’ and ‘degree’. + +covers(*degree*, *method: Optional\[str\] = None*, *cover_type: str = 'all'*) → list\[snappy.Manifold\] +Returns a list of `Manifold`s +corresponding to all of the finite covers of the given degree. The +default method is ‘low_index’ for general covers and ‘snappea’ for +cyclic covers. The former uses Sim’s algorithm while the latter uses the +original Snappea algorithm. + +WARNING: If the degree is large this might take a very, very, very long +time. + + >>> M = Manifold('m003') + >>> covers = M.covers(4) + >>> sorted(N.homology() for N in covers) + [Z/3 + Z/15 + Z, Z/5 + Z + Z] + +It is faster to look just at cyclic covers. + + >>> covers = M.covers(4, cover_type='cyclic') + >>> [(N, N.homology()) for N in covers] + [(m003~cyc~0(0,0), Z/3 + Z/15 + Z)] + +Here we check that we get the same number of covers with the ‘snappea’ +and ‘low_index’ methods. + + >>> M = Manifold('m125') + >>> len(M.covers(5)) + 19 + >>> len(M.covers(5, method='snappea')) + 19 + +If you are using Sage, you can use GAP to find the subgroups, which is +often much faster, by specifying the optional argument method = ‘gap’ If +you have Magma installed, you can used it to do the heavy lifting by +specifying method=’magma’. + +cusp_info(*data_spec=None*, *verified=False*, *bits_prec=None*) +Returns an info object containing information about the given cusp. +Usage: + + >>> M = Manifold('v3227(0,0)(1,2)(3,2)') + >>> M.cusp_info(1) + Cusp 1 : torus cusp with Dehn filling coefficients (M, L) = (1.0, 2.0) + +To get more detailed information about the cusp, we do + + >>> c = M.cusp_info(0) + >>> c.shape + 0.11044502 + 0.94677098*I + >>> c.modulus + -0.12155872 + 1.04204128*I + >>> sorted(c.keys()) + ['filling', 'holonomies', 'holonomy_accuracy', 'index', 'is_complete', 'modulus', 'shape', 'shape_accuracy', 'topology'] + +Here ‘shape’ is the shape of the cusp, i.e. (longitude/meridian) and +‘modulus’ is its shape in the geometrically preferred basis, i.e. ( +(second shortest translation)/(shortest translation)). For cusps that +are filled, one instead cares about the holonomies: + + >>> M.cusp_info(-1)['holonomies'] + (-0.59883089 + 1.09812548*I, 0.89824633 + 1.49440443*I) + +The complex numbers returned for the shape and for the two holonomies +have an extra attribute, accuracy, which is SnapPea’s *estimate* of +their accuracy. + +You can also get information about multiple cusps at once: + + >>> M.cusp_info() + [Cusp 0 : complete torus cusp of shape 0.11044502 + 0.94677098*I, + Cusp 1 : torus cusp with Dehn filling coefficients (M, L) = (1.0, 2.0), + Cusp 2 : torus cusp with Dehn filling coefficients (M, L) = (3.0, 2.0)] + >>> M.cusp_info('is_complete') + [True, False, False] + +The cusp shapes can be verified: + + sage: M = Manifold('m292') + sage: M.cusp_info('shape', verified = True, bits_prec = 60) # doctest: +NUMERIC12 + [-0.1766049820997? + 1.2028208192855?*I, + -0.1766049820997? + 1.2028208192855?*I] + +dehn_fill(*filling_data*, *which_cusp=None*) → None +Set the Dehn filling coefficients of the cusps. This can be specified in +the following ways, where the cusps are numbered by 0,1,…,(num_cusps - +1). + +- Fill cusp 2: + + >>> M = Manifold('8^4_1') + >>> M.dehn_fill((2,3), 2) + >>> M + 8^4_1(0,0)(0,0)(2,3)(0,0) + +- Fill the last cusp: + + >>> M.dehn_fill((1,5), -1) + >>> M + 8^4_1(0,0)(0,0)(2,3)(1,5) + +- Fill the first two cusps: + + >>> M.dehn_fill( [ (3,0), (1, -4) ]) + >>> M + 8^4_1(3,0)(1,-4)(2,3)(1,5) + +- When there is only one cusp, there’s a shortcut + + >>> N = Manifold('m004') + >>> N.dehn_fill( (-3,4) ) + >>> N + m004(-3,4) + +Does not return a new Manifold. + +filled_triangulation(*cusps_to_fill='all'*) → snappy.Manifold +Return a new Manifold where the specified cusps have been permanently +filled in. + +Filling all the cusps results in a Triangulation rather than a Manifold, +since SnapPea can’t deal with hyperbolic structures when there are no +cusps. + +Examples: + + >>> M = Manifold('m125(1,2)(3,4)') + >>> N = M.filled_triangulation() + >>> N.num_cusps() + 0 + +Filling cusps 0 and 2 : + + >>> M = Manifold('v3227(1,2)(3,4)(5,6)') + >>> M.filled_triangulation([0,2]) + v3227_filled(3,4) + +fundamental_group(*simplify_presentation: bool = True*, *fillings_may_affect_generators: bool = True*, *minimize_number_of_generators: bool = True*, *try_hard_to_shorten_relators: bool = True*) → HolonomyGroup +Return a +`HolonomyGroup` +representing the fundamental group of the manifold, together with its +holonomy representation. If integer Dehn surgery parameters have been +set, then the corresponding peripheral elements are killed. + + >>> M = Manifold('m004') + >>> G = M.fundamental_group() + >>> G + Generators: + a,b + Relators: + aaabABBAb + >>> G.peripheral_curves() + [('ab', 'aBAbABab')] + >>> G.SL2C('baaBA') + [ 2.50000000 - 2.59807621*I -6.06217783 - 0.50000000*I] + [ 0.86602540 - 2.50000000*I -4.00000000 + 1.73205081*I] + +There are three optional arguments all of which default to True: + +- simplify_presentation + +- fillings_may_affect_generators + +- minimize_number_of_generators + + >>> M.fundamental_group(False, False, False) + Generators: + a,b,c + Relators: + CbAcB + BacA + +homology() → AbelianGroup +Returns an +`AbelianGroup` +representing the first integral homology group of the underlying (Dehn +filled) manifold. + + >>> M = Triangulation('m003') + >>> M.homology() + Z/5 + Z + +identify(*extends_to_link=False*) +Looks for the manifold in all of the SnapPy databases. For hyperbolic +manifolds this is done by searching for isometries: + + >>> M = Manifold('m125') + >>> M.identify() + [m125(0,0)(0,0), L13n5885(0,0)(0,0), ooct01_00000(0,0)(0,0)] + +By default, there is no restriction on the isometries. One can require +that the isometry take meridians to meridians. This might return fewer +results: + + >>> M.identify(extends_to_link=True) + [m125(0,0)(0,0), ooct01_00000(0,0)(0,0)] + +For closed manifolds, extends_to_link doesn’t make sense because of how +the kernel code works: + + >>> C = Manifold("m015(1,2)") + >>> C.identify() + [m006(-5,2)] + >>> C.identify(True) + [] + +is_isometric_to(*other: Manifold \| ManifoldHP*, *return_isometries: bool = False*) → bool \| List\[Isometry\] +Returns `True` if M and N are isometric, `False` if they not. A +`RuntimeError` is raised in cases where the SnapPea kernel fails to +determine either answer. (This is fairly common for closed manifolds.) + + >>> M = Manifold('m004') + >>> N = Manifold('4_1') + >>> K = Manifold('5_2') + >>> M.is_isometric_to(N) + True + >>> N.is_isometric_to(K) + False + +We can also get a complete list of isometries between the two manifolds: + + >>> M = Manifold('5^2_1') # The Whitehead link + >>> N = Manifold('m129') + >>> isoms = M.is_isometric_to(N, return_isometries = True) + >>> isoms[6] # Includes action on cusps + 0 -> 1 1 -> 0 + [1 2] [-1 -2] + [0 -1] [ 0 1] + Extends to link + +Each transformation between cusps is given by a matrix which acts on the +left. That is, the two *columns* of the matrix give the image of the +meridian and longitude respectively. In the above example, the meridian +of cusp 0 is sent to the meridian of cusp 1. + +Note: The answer `True` is rigorous, but the answer `False` may not be +as there could be numerical errors resulting in finding an incorrect +canonical triangulation. + +is_orientable() → bool +Return whether the underlying 3-manifold is orientable. + + >>> M = Triangulation('x124') + >>> M.is_orientable() + False + +is_two_bridge() → bool +If the manifold is the complement of a two-bridge knot or link in +\\S^3\\, then this method returns \\(p,q)\\ where \\p/q\\ is the +fraction describing the link. Otherwise, returns `False`. + + >>> M = Manifold('m004') + >>> M.is_two_bridge() + (2, 5) + >>> M = Manifold('m016') + >>> M.is_two_bridge() + False + +Note: An answer of `True` is rigorous, but not the answer `False`, as +there could be numerical errors resulting in finding an incorrect +canonical triangulation. + +normal_surfaces(*algorithm='FXrays'*) +All the vertex spun-normal surfaces in the current triangulation. + + >>> M = Manifold('m004') + >>> M.normal_surfaces() + [, + , + , + ] + +num_cusps(*cusp_type='all'*) → int +Return the total number of cusps. By giving the optional argument +‘orientable’ or ‘nonorientable’ it will only count cusps of that type. + + >>> M = Triangulation('m125') + >>> M.num_cusps() + 2 + +num_tetrahedra() → int +Return the number of tetrahedra in the triangulation. + + >>> M = Triangulation('m004') + >>> M.num_tetrahedra() + 2 + +simplify(*passes_at_fours=6*) +Try to simplify the triangulation by doing Pachner moves. + + >>> M = Triangulation('12n123') + >>> M.simplify() + +It does four kinds of moves that reduce the number of tetrahedra: + +- 3 -\> 2 and 2 -\> 0 Pacher moves, which eliminate one or two + tetrahedra respectively. + +- On suitable valence-1 edges, does a 2 -\> 3 and then 2 -\> 0 move, + which removes a tetrahedron and creates a new valence-1 edge. + +- When a 2-simplex has two edges of valence-4 giving rise to the + suspension of a pentagon, replace these 6 tetrahedra with a single + edge of valence 5. + +It also does random 4 -\> 4 moves in hopes of setting up a +simplfication. The argument passes_at_fours is the number of times it +goes through the valence-4 edges without progress before giving up. + +solution_type(*enum=False*) +Returns the type of the current solution to the gluing equations, +basically a summary of how degenerate the solution is. If the flag +`enum=True` is set, then an integer value is returned. The possible +answers are: + +- 0: `not`` ``attempted` + +- 1: `all`` ``tetrahedra`` ``positively`` ``oriented` aka + *geometric_solution* + + Should correspond to a genuine hyperbolic structure. + +- 2: `contains`` ``negatively`` ``oriented`` ``tetrahedra` aka + *nongeometric solution* + + Probably corresponds to a hyperbolic structure but some simplices have + reversed orientations. + +- 3: `contains`` ``flat`` ``tetrahedra` (should be called + `all`` ``tetrahedra`` ``flat`) + + All tetrahedra have shape in \\\mathbb{R} - \\0, 1\\\\. + +- 4: `contains`` ``degenerate`` ``tetrahedra` + + Some shapes are close to \\\\0,1, \infty\\\\. + +- 5: `unrecognized`` ``solution`` ``type` + +- 6: `no`` ``solution`` ``found` + + >>> M = Manifold('m007') + >>> M.solution_type() + 'all tetrahedra positively oriented' + >>> M.dehn_fill( (3,1) ) + >>> M.solution_type() + 'contains negatively oriented tetrahedra' + >>> M.dehn_fill( (3,-1) ) + >>> M.solution_type() + 'contains degenerate tetrahedra' + +symmetry_group(*of_link: bool = False*) → SymmetryGroup +Returns the symmetry group of the Manifold. If the flag “of_link” is +set, then it only returns symmetries that preserves the meridians. + +verify_hyperbolicity(*verbose=False*, *bits_prec=None*, *holonomy=False*, *fundamental_group_args=\[\]*, *lift_to_SL=True*) +Given an orientable SnapPy Manifold, verifies its hyperbolicity. + +Similar to HIKMOT’s +`verify_hyperbolicity()`, +the result is either `(True,`` ``listOfShapeIntervals)` or +`(False,`` ``[])` if verification failed. `listOfShapesIntervals` is a +list of complex intervals (elements in sage’s `ComplexIntervalField`) +certified to contain the true shapes for the hyperbolic manifold. + +Higher precision intervals can be obtained by setting `bits_prec`: + + sage: from snappy import Manifold + sage: M = Manifold("m019") + sage: M.verify_hyperbolicity() # doctest: +NUMERIC12 + (True, [0.780552527850? + 0.914473662967?*I, 0.780552527850? + 0.91447366296773?*I, 0.4600211755737? + 0.6326241936052?*I]) + + sage: M = Manifold("t02333(3,4)") + sage: M.verify_hyperbolicity() # doctest: +NUMERIC9 + (True, [2.152188153612? + 0.284940667895?*I, 1.92308491369? + 1.10360701507?*I, 0.014388591584? + 0.143084469681?*I, -2.5493670288? + 3.7453498408?*I, 0.142120333822? + 0.176540027036?*I, 0.504866865874? + 0.82829881681?*I, 0.50479249917? + 0.98036162786?*I, -0.589495705074? + 0.81267480427?*I]) + +One can instead get a holonomy representation associated to the verified +hyperbolic structure. This representation takes values in 2x2 matrices +with entries in the `ComplexIntervalField`: + + sage: M = Manifold("m004(1,2)") + sage: success, rho = M.verify_hyperbolicity(holonomy=True) + sage: success + True + sage: trace = rho('aaB').trace(); trace # doctest: +NUMERIC9 + -0.1118628555? + 3.8536121048?*I + sage: (trace - 2).contains_zero() + False + sage: (rho('aBAbaabAB').trace() - 2).contains_zero() + True + +Here, there is **provably** a fixed holonomy representation rho0 from +the fundamental group G of M to SL(2, C) so that for each element g of G +the matrix rho0(g) is contained in rho(g). In particular, the above +constitutes a proof that the word ‘aaB’ is non-trivial in G. In +contrast, the final computation is consistent with ‘aBAbaabAB’ being +trivial in G, but *does not prove this*. + +A non-hyperbolic manifold (`False` indicates that the manifold might not +be hyperbolic but does **not** certify non-hyperbolicity. Sometimes, +hyperbolicity can only be verified after increasing the precision): + + sage: M = Manifold("4_1(1,0)") + sage: M.verify_hyperbolicity() + (False, []) + +Under the hood, the function will call the `CertifiedShapesEngine` to +produce intervals certified to contain a solution to the rectangular +gluing equations. It then calls +`check_logarithmic_gluing_equations_and_positively_oriented_tets` to +verify that the logarithmic gluing equations are fulfilled and that all +tetrahedra are positively oriented. + +volume(*accuracy=False*, *verified=False*, *bits_prec=None*) +Returns the volume of the current solution to the hyperbolic gluing +equations; if the solution is sufficiently non-degenerate, this is the +sum of the volumes of the hyperbolic pieces in the geometric +decomposition of the manifold. + + >>> M = Manifold('m004') + >>> M.volume() + 2.02988321 + >>> M.solution_type() + 'all tetrahedra positively oriented' + +The return value has an extra attribute, accuracy, which is the number +of digits of accuracy as *estimated* by SnapPea. When printing the +volume, the result is rounded to 1 more than this number of digits. + + >>> vol, accuracy = M.volume(accuracy = True) + >>> accuracy in (10, 63) # Low precision, High precision + True + +Inside SageMath, verified computation of the volume of a hyperbolic +manifold is also possible (this will verify first that the manifold is +indeed hyperbolic): + + sage: M.volume(verified=True, bits_prec=100) #doctest: +NUMERIC24 + 2.029883212819307250042405109? + +# Census manifolds + +Snappy comes with a large library of manifolds, which can be accessed +individually through the Manifold and Triangulation constructors but can +also be iterated through using the objects described on this page. + +SnapPy’s iterators support several flexible methods for accessing +manifolds. They can be sliced (i.e. restricted to subranges) either by +index or by volume. Calling the iterator with keyword arguments such as +num_tets=1, betti=2 or num_cusps=3 returns an iterator which is filtered +by the specified conditions. In addition these iterators can determine +whether they contain a given manifold. They support python’s “A in B” +syntax, and also provide an identify method which will return a copy of +the census manifold which is isometric to the manifold passed as an +argument. + +snappy.OrientableCuspedCensus* = OrientableCuspedCensus without filters* +Iterator for all orientable cusped hyperbolic manifolds that can be +triangulated with at most 10 ideal tetrahedra. See +[\[Li\]](https://arXiv.org/abs/2512.02142) for background on these +manifolds. + + >>> for M in OrientableCuspedCensus[3:6]: print(M, M.volume()) + ... + m007(0,0) 2.56897060 + m009(0,0) 2.66674478 + m010(0,0) 2.66674478 + >>> for M in OrientableCuspedCensus[-9:-6]: print(M, M.volume()) + ... + o10_150721(0,0)(0,0)(0,0) 10.1494160640965 + o10_150722(0,0)(0,0)(0,0) 10.1494160640965 + o10_150723(0,0)(0,0) 10.1494160640965 + >>> for M in OrientableCuspedCensus[4.10:4.11]: print(M, M.volume()) + ... + m217(0,0) 4.10795310 + m218(0,0) 4.10942659 + >>> for M in OrientableCuspedCensus(num_cusps=2)[:3]: + ... print(M, M.volume(), M.num_cusps()) + ... + m125(0,0)(0,0) 3.66386238 2 + m129(0,0)(0,0) 3.66386238 2 + m202(0,0)(0,0) 4.05976643 2 + >>> M = Manifold('m129') + >>> M in LinkExteriors + True + >>> LinkExteriors.identify(M) + 5^2_1(0,0)(0,0) + +  + +snappy.OrientableClosedCensus* = OrientableClosedCensus without filters* +Iterator for 11,031 closed hyperbolic manifolds from the census by +Hodgson and Weeks. + + >>> len(OrientableClosedCensus) + 11031 + >>> len(OrientableClosedCensus(betti=2)) + 1 + >>> for M in OrientableClosedCensus(betti=2): + ... print(M, M.homology()) + ... + v1539(5,1) Z + Z + +  + +snappy.CensusKnots* = CensusKnots without filters* +Iterator for all of the knot exteriors in the SnapPea Census, as +tabulated by Callahan, Dean, Weeks, Champanerkar, Kofman, Patterson, +Dunfield, and Li. These are the knot exteriors which can be triangulated +by at most 10 ideal tetrahedra. See +[\[Li\]](https://arXiv.org/abs/2512.02142) for more. + + >>> for M in CensusKnots[3.4:3.5]: + ... print(M, M.volume(), LinkExteriors.identify(M)) + ... + K4_3(0,0) 3.47424776 False + K5_1(0,0) 3.41791484 False + K5_2(0,0) 3.42720525 8_1(0,0) + K5_3(0,0) 3.48666015 9_2(0,0) + + >>> len(CensusKnots) + 3116 + >>> CensusKnots[-1].num_tetrahedra() + 10 + +  + +snappy.LinkExteriors* = LinkExteriors without filters* +Iterator for all knots with at most 11 crossings and links with at most +10 crossings, using the Rolfsen notation. The triangulations were +computed by Joe Christy. + + >>> for K in LinkExteriors(num_cusps=3)[-3:]: + ... print(K, K.volume()) + ... + 10^3_72(0,0)(0,0)(0,0) 14.35768903 + 10^3_73(0,0)(0,0)(0,0) 15.86374431 + 10^3_74(0,0)(0,0)(0,0) 15.55091438 + >>> M = Manifold('8_4') + >>> OrientableCuspedCensus.identify(M) + s862(0,0) + +By default, the ‘identify’ returns the first isometric manifold it +finds; if the optional ‘extends_to_link’ flag is set, it insists that +meridians are taken to meridians. + + >>> M = Manifold('7^2_8') + >>> LinkExteriors.identify(M) + 5^2_1(0,0)(0,0) + >>> LinkExteriors.identify(M, extends_to_link=True) + 7^2_8(0,0)(0,0) + +  + +snappy.HTLinkExteriors* = HTLinkExteriors without filters* +Iterator for all knots up to 14 or 15 crossings (see below for which) +and links up to 14 crossings as tabulated by Jim Hoste and Morwen +Thistlethwaite. In addition to the filter arguments supported by all +ManifoldTables, this iterator provides alternating=\; +knots_vs_links=\<’knots’/’links’\>; and crossings=N. These allow +iterations only through alternating or non-alternating links with 1 or +more than 1 component and a specified crossing number. + + >>> HTLinkExteriors.identify(LinkExteriors['8_20']) + K8n1(0,0) + >>> Mylist = HTLinkExteriors(alternating=False,knots_vs_links='links')[8.5:8.7] + >>> len(Mylist) + 8 + >>> for L in Mylist: + ... print( L.name(), L.num_cusps(), L.volume() ) + ... + L11n138 2 8.66421454 + L12n1097 2 8.51918360 + L14n13364 2 8.69338342 + L14n13513 2 8.58439465 + L14n15042 2 8.66421454 + L14n24425 2 8.60676092 + L14n24777 2 8.53123093 + L14n26042 2 8.64333782 + >>> for L in Mylist: + ... print( L.name(), L.DT_code() ) + ... + L11n138 [(8, -10, -12), (6, -16, -18, -22, -20, -2, -4, -14)] + L12n1097 [(10, 12, -14, -18), (22, 2, -20, 24, -6, -8, 4, 16)] + L14n13364 [(8, -10, 12), (6, -18, 20, -22, -26, -24, 2, -4, -28, -16, -14)] + L14n13513 [(8, -10, 12), (6, -20, 18, -26, -24, -4, 2, -28, -16, -14, -22)] + L14n15042 [(8, -10, 14), (12, -16, 18, -22, 24, 2, 26, 28, 6, -4, 20)] + L14n24425 [(10, -12, 14, -16), (-18, 26, -24, 22, -20, -28, -6, 4, -2, 8)] + L14n24777 [(10, 12, -14, -18), (2, 28, -22, 24, -6, 26, -8, 4, 16, 20)] + L14n26042 [(10, 12, 14, -20), (8, 2, 28, -22, -24, -26, -6, -16, -18, 4)] + +SnapPy comes with one of two versions of HTLinkExteriors. The smaller +original one provides knots and links up to 14 crossings; the larger +adds to that the knots (but not links) with 15 crossings. You can +determine which you have by whether + + >>> len(HTLinkExteriors(crossings=15)) + +gives 0 or 253293. To upgrade to the larger database, install the Python +module ‘snappy_15_knots’ as discussed on the ‘installing SnapPy’ +webpage. + +  + +snappy.RibbonLinks* = RibbonLinks without filters* +The database of ribbon links from Section 2.5 of [\[Dunfield and +Gong\]](https://arXiv.org/abs/2512.21825). Each link includes a +certificate describing the ribbon disks: + + >>> len(RibbonLinks(cusps=2)) + 12143 + >>> M = RibbonLinks[1000] + >>> M.name(), M.num_cusps(), M.volume() + ('ribbon_2_16_3079d007', 2, 22.9002274714046) + +The bands used show each link is ribbon are included. For this link, we +used 3 bands: + + >>> N = RibbonLinks['ribbon_2_23_f9c7aff2'] + >>> N.ribbon_cert[1::2] + ['0d1c54_1_0', '5e5709_1_0', '144f625e5d29_5_2'] + +  + +snappy.NonorientableCuspedCensus* = NonorientableCuspedCensus without filters* +Iterator for all nonorientable cusped hyperbolic manifolds that can be +triangulated with at most 5 ideal tetrahedra. + + >>> for M in NonorientableCuspedCensus(betti=2)[:3]: + ... print(M, M.homology()) + ... + m124(0,0)(0,0)(0,0) Z/2 + Z + Z + m128(0,0)(0,0) Z + Z + m131(0,0) Z + Z + +  + +snappy.NonorientableClosedCensus* = NonorientableClosedCensus without filters* +Iterator for 17 nonorientable closed hyperbolic manifolds from the +census by Hodgson and Weeks. + + >>> for M in NonorientableClosedCensus[:3]: print(M, M.volume()) + ... + m018(1,0) 2.02988321 + m177(1,0) 2.56897060 + m153(1,0) 2.66674478 + +There are also: + +- Censuses of Platonic manifolds + +As instances of subclasses of ManifoldTable, the objects above support +the following methods. + +*class *snappy.database.ManifoldTable(*table=''*, *db_path=None*, *mfld_hash=\*, *\*\*filter_args*) +Iterator for cusped manifolds in an sqlite3 table of manifolds. + +Initialize with the table name. The table schema is required to include +a text field called ‘name’ and a text field called ‘triangulation’. The +text holds the result of M.triangulation_isosig(), +M.triangulation_isosig(decorated = True), or M.\_to_string(). + +Both mapping from the manifold name, and lookup by index are supported. +Slicing can be done either by numerical index or by volume. + +The \_\_contains\_\_ method is supported, so M in T returns True if M is +isometric to a manifold in the table T. The method T.identify(M) will +return the matching manifold from the table. + +find(*where=None*, *order_by='id'*, *limit=None*, *offset=None*) +Return a list of up to limit manifolds stored in this table, satisfying +the where clause, and ordered by the order_by clause. If limit is None, +all matching manifolds are returned. If the offset parameter is set, the +first offset matches are skipped. + +identify(*mfld*, *extends_to_link=False*) +Look for a manifold in this table which is isometric to the argument. + +Return the matching manifold, if there is one which SnapPea declares to +be isometric. + +Return False if no manifold in the table has the same hash. + +Return None in all other cases (for now). + +If the flag “extends_to_link” is True, requires that the isometry sends +meridians to meridians. If the input manifold is closed this will result +in no matches being returned. + +keys() +Return the list of column names for this manifold table. + +siblings(*mfld*) +Return all manifolds in the census which have the same hash value. + +Because of the large size of their datasets, the classes below can only +iterate through slices by index, and do not provide the identification +methods. + +*class *snappy.AlternatingKnotExteriors(*indices=(0, 491327, 1)*) +Iterator/Sequence for Alternating knot exteriors from the +Hoste-Thistlethwaite tables. Goes through 16 crossings. + +  + +*class *snappy.NonalternatingKnotExteriors(*indices=(0, 1210608, 1)*) +Iterator/Sequence for nonAlternating knot exteriors from the +Hoste-Thistlethwaite tables. Goes through 16 crossings. + +# Verified computations + +## Introduction + +Several SnapPy methods use numerical computations with floating point +approximations and can potentially result in incorrect results. This +even applies to methods whose output is purely combinatorial such as +`canonical_retriangulation()`. + +Many of these SnapPy methods can be supplied with a `verified` flag to +ensure that the result is provably correct. Note that verified +computations are only available when using SnapPy inside +SageMath. If the flag `verified=True` is +specified, an incorrect result is never returned. Instead the method +clearly indicates a failure, usually through an exception: + + sage: M=Manifold("m004") + sage: M.drill_word('abc', verified=True, bits_prec = 40) + ... + InsufficientPrecisionError: When re-tracing the geodesic, the intersection with the next tetrahedron face was too close to the previous to tell them apart. Increasing the precision will probably avoid this problem. + +Often, such a failure can be advoided by increasing the precision. In +particular, this applies if the exception is a (subclass of) +`InsufficientPrecisionError`: + + sage: M.drill_word('abc', verified=True, bits_prec = 60) + m004_drilled(0,0)(0,0) + +Note that, +`verify_hyperbolicity()` +is different though and does not throw an exception. Instead, it returns +a bool indicating success as part of its output. This is for +compatibility with +HIKMOT’s +`verify_hyperbolicty`: + + sage: M.verify_hyperbolicity(bits_prec=10) + (False, []) + sage: M.verify_hyperbolicity() + (True, + [0.50000000000000? + 0.86602540378444?*I, + 0.50000000000000? + 0.86602540378444?*I]) + +As illustrated above, the result consists of intervals (of type +SageMath’s `RealIntervalField` or `ComplexIntervalField`) if the output +of a computation is numerical and `verified=True` is specified. These +intervals contain the true value. + +## Overview + +Some examples of verified computations are: + +- Verify the hyperbolicity of an orientable 3-manifold giving complex + intervals for the shapes corresponding to a hyperbolic structure or + holonomy representation with + `verify_hyperbolicity()`: + + sage: M = Manifold("m015") + sage: M.verify_hyperbolicity() + (True, + [0.6623589786224? + 0.5622795120623?*I, + 0.6623589786224? + 0.5622795120623?*I, + 0.6623589786224? + 0.5622795120623?*I]) + sage: M.verify_hyperbolicity(holonomy=True)[1].SL2C('a') + [-0.324717957? - 1.124559024?*I -0.704807293? + 0.398888830?*I] + [ 1.409614585? - 0.797777659?*I -1.000000000? + 0.?e-9*I] + +- Intervals for the volume and complex volume of a hyperbolic orientable + 3-manifold: + + sage: M = Manifold("m003(-3,1)") + sage: M.volume(verified=True, bits_prec = 100) + 0.942707362776927720921299603? + sage: M = Manifold("m015") + sage: M.complex_volume(verified_modulo_2_torsion=True) + 2.8281220883? + 1.9106738240?*I + + (Note that when using verified computation, the Chern-Simons invariant + is only computed modulo pi^2/2 even though it is defined modulo pi^2.) + +- Give the (a close relative to the canonical cell decomposition) of a + cusped hyperbolic manifold using intervals or exact arithmetic if + necessary with + `canonical_retriangulation()`: + + sage: M = Manifold("m412") + sage: K = M.canonical_retriangulation(verified = True) + sage: len(K.isomorphisms_to(K)) # Certified size of isometry group + 8 + + **Remark:** For the case of non-tetrahedral canonical cell, exact + values are used which are found using the + LLL-algorithm + and then verified using exact computations. These computations can be + slow. A massive speed-up was achieved by recent improvements so that + the computation of the isometry signature of any manifold in + `OrientableCuspedCensus` takes at most a couple of seconds, typically, + far less. Manifolds with more simplices might require setting a higher + value for `exact_bits_prec_and_degrees`. + +- The isometry signature which is a complete invariant of the isometry + type of a cusped hyperbolic manifold (i.e., two manifolds are + isometric if and only if they have the same isometry signature): + + sage: M = Manifold("m412") + sage: M.isometry_signature(verified = True) + 'mvvLALQQQhfghjjlilkjklaaaaaffffffff' + + The isometry signature can be strengthened to include the peripheral + curves such that it is a complete invariant of a hyperbolic link: + + sage: M = Manifold("L5a1") + sage: M.isometry_signature(of_link = True, verified = True) + 'eLPkbdcddhgggb_baCbbaCb' + + See + `isometry_signature()` + for details. + + **Remark:** The isometry signature is based on the canonical + retriangulation so the same warning applies. + +- The maximal cusp area matrix which characterizes the configuration + space of disjoint cusp neighborhoods with + `cusp_area_matrix()`: + + sage: M=Manifold("m203") + sage: M.cusp_area_matrix(method='maximal', verified=True) + [ 27.000000? 9.0000000000?] + [9.0000000000? 27.0000000?] + + In this example, the cusp neighborhood about cusp 0 or 1 is only + embedded if and only if its area is less than sqrt(27). The cusp + neighborhood about cusp 0 is only disjoint from the one about cusp 1 + if and only if the product of their areas is less than 9. + +- Compute areas for disjoint cusp neighborhoods with + `cusp_areas()`: + + sage: M=Manifold("m203") + sage: M.cusp_areas(policy = 'unbiased', method='maximal', verified = True) + [3.00000000000?, 3.00000000000?] + + With the above parameters, the result is intrinsic to the hyperbolic + manifold with labeled cusped. + +- Find all slopes of length less or equal to 6 when measured on the + boundary of disjoint cusp neighborhoods: + + sage: M=Manifold("m203") + sage: M.short_slopes(policy = 'unbiased', method='maximal', verified = True) + [[(1, 0), ..., (1, 2)], [(1, 0), ..., (1, 2)]] + + First block has all short slopes for first cusp, …, see + `short_slopes()` + for details. + + By Agol’s and + Lackenby’s 6-Theorem any + Dehn-filling resulting in a non-hyperbolic manifold must contain one + of the above slopes. Thus, + `short_slopes()` + can be used to implement the techniques to find exceptional Dehn + surgeries (arXiv:1109.0903 and + arXiv:1310.3472). + +- An example of finding all geodesics up to length 1: + + sage: from snappy.sage_helper import RIF + sage: L = RIF(1) + sage: M = Manifold("m003") + sage: spec = M.length_spectrum_alt_gen(verified=True) + sage: n = 0 + sage: for g in spec: + ... if g.length.real() > L: + ... break # Done! All subsequent geodesics will be longer. + ... if g.length.real() < L: + ... n += 1 + ... continue + ... raise Exception("Interval too large. Increase precision.") + sage: n + 4 + +Additionally, we can compute complex intervals for the shapes that are +guaranteed to contain a true solution to the rectangular gluing +equations that is not necessarily a geometric solution (specify +`bits_prec` or `dec_prec` for higher precision intervals.): + + sage: M = Manifold("m015(3,1)") + sage: M.tetrahedra_shapes('rect', intervals=True) + [0.625222762246? + 3.177940133813?*I, + -0.0075523593782? + 0.5131157955971?*I, + 0.6515818912107? - 0.1955023488930?*I] + +This is all based on a reimplementation of +HIKMOT which +pioneered the use of interval methods for hyperbolic manifolds (also see +Zgliczynski’s +notes). It can be +used in a way very similar to HIKMOT, but uses Sage’s complex interval +types for certification. It furthermore makes use of code by Dunfield, +Hoffman, Licata. + +This verification code was contributed by Matthias Goerner. + +## Verified computation topics + +- Internals of verified computations diff --git a/apn/lean/loogle.sh b/apn/lean/loogle.sh new file mode 100644 index 00000000..4840df30 --- /dev/null +++ b/apn/lean/loogle.sh @@ -0,0 +1,19 @@ +#!/bin/bash +# Wrapper for the Loogle CLI (built in the Dockerfile's loogle_build stage). +# Loogle ignores LEAN_PATH -- its --path flags REPLACE the compiled-in search +# path entirely -- so every olean root is listed explicitly: the FC project's +# packages (Mathlib and its deps; the same rev loogle was built against), the +# project's own build, loogle's modules, and the toolchain's stdlib (derived +# from the project's lean-toolchain: "leanprover/lean4:vX" installs under +# "leanprover--lean4---vX"). The prebuilt index skips index construction, not +# the ~30s Mathlib import -- batch queries via `loogle -i` reading stdin. +set -euo pipefail +ARGS=() +for p in /workspace/leanproject/.lake/packages/*/.lake/build/lib/lean; do + ARGS+=(--path "$p") +done +ARGS+=(--path /workspace/leanproject/.lake/build/lib/lean) +ARGS+=(--path /opt/loogle/lib/lean) +tc_dir="$(sed 's|/|--|g; s|:|---|g' /workspace/leanproject/lean-toolchain)" +ARGS+=(--path "/root/.elan/toolchains/${tc_dir}/lib/lean") +exec /opt/loogle/bin/loogle "${ARGS[@]}" --read-index /opt/loogle/loogle.index "$@" diff --git a/apn/prompts.py b/apn/prompts.py index 531ce088..f1147927 100644 --- a/apn/prompts.py +++ b/apn/prompts.py @@ -48,9 +48,9 @@ def user_prompt(path: str, token_limit: int | None, literature: bool, util_modul Your submission may depend only on the following axioms: {', '.join(f'`{a}`' for a in PERMITTED_AXIOMS)}. Don't attempt to cheat with Lean loopholes, the verifier will reject such attempts. Your environment has the following available: -* A Lean 4 toolchain with Mathlib, plus `loogle` for searching Mathlib by constant name or type pattern (e.g. `loogle 'Nat.Prime, _ ^ _'` or `loogle '|- tsum _ = _ * tsum _'`). To inspect a goal state, insert `trace_state` into a tactic proof and run `lake env lean `: the goal is printed on stdout (an unfinished proof likewise prints its unsolved goals). +* A Lean 4 toolchain with Mathlib, plus the `loogle` search CLI. * The `sage` computer algebra system (version 10), with `gp` (PARI), `gap`, `Singular`, and `maxima` also on PATH. -* `python3` with numpy, scipy, sympy, mpmath, pandas, networkx, igraph, python-flint (fast arbitrary-precision number theory), highspy (LP/MIP), python bindings for the solvers below (z3, cvc5, OR-Tools CP-SAT, pysat), snappy (SnapPy, 3-manifolds), and ore_algebra (D-finite sequences, used from sage). +* `python3` with numpy, scipy, sympy, mpmath, pandas, networkx, igraph, python-flint, highspy (LP/MIP), python bindings for the solvers below (z3, cvc5, OR-Tools CP-SAT, pysat), snappy (SnapPy, 3-manifolds), and ore_algebra (D-finite sequences, used from sage). * Solver binaries: `z3`, `cvc5`, `kissat` (SAT, DIMACS), `cryptominisat` (SAT), `csdp` (semidefinite programs), `msolve` (polynomial systems), `prover9`/`mace4` (first-order prover / countermodel finder). * Mathematical CLI tools: `primesieve`, `primecount`, `ecm` (integer factorization), nauty's generators (`geng`, `genbg`, ...), `plantri` (planar graphs), `polymake` (polyhedral geometry), `normaliz` (rational cones), 4ti2 (lattice ideals), `lrs` (vertex enumeration), `M2` (Macaulay2, commutative algebra), `regina-python` (low-dimensional topology). * `git`, `rg`, and `jq` diff --git a/tests/test_agent_image.py b/tests/test_agent_image.py index f88436cb..151c9064 100644 --- a/tests/test_agent_image.py +++ b/tests/test_agent_image.py @@ -100,7 +100,10 @@ "ortools", "pysat", # python-sat "snappy", # SnapPy - "ore_algebra", + # ore_algebra is a sage library: importing it before sage.all trips sage's + # circular-import guard, so the contract (and the agent's usage) is + # "import sage.all first". + "sage.all, ore_algebra", "sage.all", ] diff --git a/tests/test_tools.py b/tests/test_tools.py index 9e97a1b7..d17241d4 100644 --- a/tests/test_tools.py +++ b/tests/test_tools.py @@ -31,7 +31,6 @@ def test_user_prompt_mentions_environment_tools() -> None: assert "sage" in rendered assert "z3" in rendered assert "kissat" in rendered - assert "trace_state" in rendered assert "/opt/docs" in rendered # The pantograph toolchain is gone from the image; the prompt must not # advertise it. From 47f33914f482eb4caef2d6d4ea04e9c34444911e Mon Sep 17 00:00:00 2001 From: tadamcz Date: Fri, 28 Aug 2026 23:59:21 +0100 Subject: [PATCH 3/7] Simplify Loogle to a flag-less binary; drop ore_algebra Loogle is now built as its own project at /opt/loogle with .lake/packages symlinked to the FC project's checkouts: lake update resolves its deps to exactly the project's pinned revs (nothing re-clones, Mathlib replays from the existing oleans), the binary's compile-time-embedded search path is the agent image's real layout, and the search index sits at the canonical LoogleMathlibCache.extra location the binary checks by itself. The agent image copies the raw binary, loogle's olean/index lib, and recreates the symlink -- the runtime shell wrapper and its --path roster are gone. (Adding loogle to the FC project itself was tried and rejected: lake update loogle drags transitive deps to loogle's stale manifest revs.) ore_algebra is dropped as low-value-high-pain: no PyPI release, a patched setup.py, and only the degraded pure-python build was possible anyway since sage 10.9's Cython >= 3.2 cannot compile its extensions; its common use is covered by sage's berlekamp_massey or a hand-rolled ansatz solve. With it go the setuptools pin and the stage's compiler/pkg-config, leaving the pip layer as four pinned wheels. Verified: full contract suite green against the rebuilt image. --- apn/lean/Dockerfile | 94 +- apn/lean/compute-env.yaml | 5 +- apn/lean/docs/ore_algebra/LICENSE | 339 ----- apn/lean/docs/ore_algebra/ore_algebra.md | 1709 ---------------------- apn/lean/loogle-build.sh | 57 + apn/lean/loogle.sh | 19 - apn/prompts.py | 2 +- tests/test_agent_image.py | 5 - 8 files changed, 81 insertions(+), 2149 deletions(-) delete mode 100644 apn/lean/docs/ore_algebra/LICENSE delete mode 100644 apn/lean/docs/ore_algebra/ore_algebra.md create mode 100644 apn/lean/loogle-build.sh delete mode 100644 apn/lean/loogle.sh diff --git a/apn/lean/Dockerfile b/apn/lean/Dockerfile index 2eb2a827..be1bf9c5 100644 --- a/apn/lean/Dockerfile +++ b/apn/lean/Dockerfile @@ -245,10 +245,8 @@ FROM debian:bookworm-slim AS compute_build ENV DEBIAN_FRONTEND=noninteractive -# build-essential + pkg-config: ore_algebra below compiles Cython extensions -# against the env's sage/flint headers (its setup probes flint via pkg-config). RUN apt-get update && apt-get install -y --no-install-recommends \ - curl ca-certificates bzip2 git build-essential pkg-config \ + curl ca-certificates bzip2 \ && rm -rf /var/lib/apt/lists/* ARG MICROMAMBA_VERSION=2.9.0 @@ -261,29 +259,13 @@ COPY compute-env.yaml /tmp/compute-env.yaml RUN micromamba create -y -p /opt/env -f /tmp/compute-env.yaml \ && micromamba clean -afy -# PyPI-only packages, into the same env. snappy is SnapPy (3-manifold -# topology), not the compression lib. ore_algebra (D-finite guessing over -# Sage) has no PyPI release, so it is pinned by commit; its setup.py imports -# sage.env, so it must build WITHOUT pip's build isolation, against the env's -# own sage/cython (hence --no-build-isolation and the env's setuptools). Its -# optional compiled arb extensions do not build under Cython >= 3.2 (which -# sage 10.9 requires env-wide), so the setup is patched onto its own -# no-extensions branch -- the pure-python install it already uses for older -# sage; the guessing/annihilator API is pure python, only numerical -# evaluation loses its fast path. -ARG ORE_ALGEBRA_COMMIT=18680180c884fac869a064db99f29a221aad9dfe +# PyPI-only packages (prebuilt wheels), into the same env. snappy is SnapPy +# (3-manifold topology), not the compression lib. RUN /opt/env/bin/pip install --no-cache-dir \ python-sat==1.9.dev15 \ cvc5==1.3.4 \ ortools==9.15.6755 \ snappy==3.3.2 \ - && curl -sSfL "https://github.com/mkauers/ore_algebra/archive/${ORE_ALGEBRA_COMMIT}.tar.gz" \ - | tar xz -C /tmp \ - && cd /tmp/ore_algebra-* \ - && sed -i "s|^if list(map(int, sage.version.version.split('.')\\[:2\\])) < \\[10, 2\\]:|if True: # patched: pure-python install, Cython >= 3.2 cannot build the arb extensions|" setup.py \ - && grep -q '^if True:' setup.py \ - && /opt/env/bin/pip install --no-cache-dir --no-build-isolation . \ - && cd / && rm -rf /tmp/ore_algebra-* \ && find /opt/env -name '__pycache__' -type d -prune -exec rm -rf {} + # --------------------------------------------------------------------------- # @@ -364,55 +346,20 @@ RUN arch="$(uname -m)" \ # --------------------------------------------------------------------------- # # loogle_build: the Loogle type-pattern Mathlib search CLI, the one pin-tied # -# addition to the agent's compute stack. Built FROM base so it compiles at # -# the PROJECT toolchain against the PROJECT's Mathlib rev (read from the # -# baked lake-manifest.json): the binary importModules-loads Mathlib oleans at # -# runtime, and the agent image reuses the FC project's own oleans via # -# LEAN_PATH (see the loogle wrapper in `agent`) rather than shipping a second # -# multi-GB Mathlib. The Loogle rev is chosen inside the pin's toolchain # -# window (its own lean-toolchain is overwritten with the project's, exactly # -# like lean4export_build). # +# addition to the agent's compute stack. Built FROM base at /opt/loogle, # +# retargeted to the project's toolchain + pinned Mathlib rev and sharing the # +# project's package checkouts via symlink (loogle-build.sh) -- so the binary # +# compiles against the very oleans the agent image carries, its embedded # +# search path resolves at runtime, and its search index sits where it # +# auto-finds it. The agent stage copies the raw binary plus loogle's build # +# lib and recreates the symlink: no second Mathlib, no wrapper, no flags. # +# The Loogle rev is chosen inside the pin's toolchain window. # # --------------------------------------------------------------------------- # FROM base AS loogle_build -# Retarget: the project's toolchain file replaces loogle's (v4.27.0-rc1 -> -# v4.27.0; verified friction-free), and its mathlib require moves from -# "master" to the rev the baked manifest pins. `lake update` then resolves -# the transitive deps to exactly the FC manifest's revs and mathlib's -# post-update hook fetches the olean cache (zero misses at the pinned rev). ARG LOOGLE_COMMIT=79343e3e37b64046e6b555936682012e80300df1 -RUN git clone https://github.com/nomeata/loogle.git /opt/loogle-src \ - && git -C /opt/loogle-src checkout --detach "${LOOGLE_COMMIT}" \ - && cd /opt/loogle-src \ - && cp /workspace/leanproject/lean-toolchain lean-toolchain \ - && MATHLIB_REV="$(python3 -c "import json; print(next(p['rev'] for p in json.load(open('/workspace/leanproject/lake-manifest.json'))['packages'] if p['name'] == 'mathlib'))")" \ - && sed -i "s|@ \"master\"|@ \"${MATHLIB_REV}\"|" lakefile.lean \ - && grep -q "@ \"${MATHLIB_REV}\"" lakefile.lean \ - && rm lake-manifest.json \ - && lake update \ - && lake build loogle - -# Stage the runtime pieces -- the binary (statically linked against the -# toolchain: no lake env / LD_LIBRARY_PATH needed), loogle's own module -# oleans, and the prebuilt search index (built here, where a Mathlib rev -# identical to the runtime one is guaranteed; peaks ~10 GB RSS). Its -# Mathlib/dependency oleans are NOT staged: at runtime the wrapper passes -# --path flags for the FC project's baked packages, same toolchain and -# Mathlib rev by construction. The --json query doubles as a smoke test. -RUN mkdir -p /opt/loogle/bin /opt/loogle/lib \ - && cp /opt/loogle-src/.lake/build/bin/loogle /opt/loogle/bin/loogle \ - && cp -r /opt/loogle-src/.lake/build/lib/lean /opt/loogle/lib/lean \ - && find /opt/loogle/lib -type f ! -name '*.olean' -delete \ - && /opt/loogle/bin/loogle \ - $(for p in /workspace/leanproject/.lake/packages/*/.lake/build/lib/lean; do printf ' --path %s' "$p"; done) \ - --path /workspace/leanproject/.lake/build/lib/lean \ - --path /opt/loogle/lib/lean \ - --path "/root/.elan/toolchains/$(sed 's|/|--|g; s|:|---|g' /workspace/leanproject/lean-toolchain)/lib/lean" \ - --write-index /opt/loogle/loogle.index --json "Nat.Prime" \ - > /tmp/loogle-smoke.json \ - && grep -q '"name"' /tmp/loogle-smoke.json \ - && rm /tmp/loogle-smoke.json \ - && rm -rf /opt/loogle-src +COPY loogle-build.sh /tmp/loogle-build.sh +RUN bash /tmp/loogle-build.sh "${LOOGLE_COMMIT}" # --------------------------------------------------------------------------- # # agent: the agent's workspace. Layer order is big/stable first (the conda # @@ -443,13 +390,14 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # Source-built solvers (kissat, plantri, prover9/mace4, msolve, cvc5). COPY --from=solvers_build /out/bin/ /usr/local/bin/ -# Loogle: binary + its own module oleans + prebuilt index; Mathlib resolves -# from the FC project's baked packages (same toolchain + Mathlib rev as the -# loogle_build stage by construction). The wrapper passes the --path roster -# so `loogle "..."` works without the agent knowing any of this. -COPY --from=loogle_build /opt/loogle /opt/loogle -COPY loogle.sh /usr/local/bin/loogle -RUN chmod 755 /usr/local/bin/loogle +# Loogle: the raw binary, its module oleans + search index at the paths the +# binary's compile-time-embedded search path expects, and the packages +# symlink through which that embedded path reaches the project's own Mathlib +# oleans (same revs as the build, by construction -- see loogle-build.sh). +# No wrapper, no flags: `loogle "..."` just works. +COPY --from=loogle_build /opt/loogle/.lake/build/bin/loogle /usr/local/bin/loogle +COPY --from=loogle_build /opt/loogle/.lake/build/lib /opt/loogle/.lake/build/lib +RUN ln -s /workspace/leanproject/.lake/packages /opt/loogle/.lake/packages # In-sandbox references (the sandbox has no network): vendored, version-matched # docs for the tools whose syntax the agent is unlikely to know cold. Last: diff --git a/apn/lean/compute-env.yaml b/apn/lean/compute-env.yaml index 98b7c9c6..4c83b89d 100644 --- a/apn/lean/compute-env.yaml +++ b/apn/lean/compute-env.yaml @@ -10,15 +10,14 @@ # verified for linux-64 and linux-aarch64 (local dev on Apple silicon); when # bumping a pin, keep versions that exist for both platforms. # -# pip-layer packages (python-sat, cvc5 bindings, ortools, snappy, ore_algebra) -# are installed into this same env by the Dockerfile, pinned there. +# pip-layer packages (python-sat, cvc5 bindings, ortools, snappy) are +# installed into this same env by the Dockerfile, pinned there. name: compute channels: - conda-forge dependencies: - python=3.13.15 - pip=26.2.1 - - setuptools=84.0.0 # ore_algebra's no-isolation pip build needs it # computer algebra systems and their engines - sage=10.9 - pari=2.17.3 # PARI/GP: the `gp` binary + libpari diff --git a/apn/lean/docs/ore_algebra/LICENSE b/apn/lean/docs/ore_algebra/LICENSE deleted file mode 100644 index d159169d..00000000 --- a/apn/lean/docs/ore_algebra/LICENSE +++ /dev/null @@ -1,339 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. diff --git a/apn/lean/docs/ore_algebra/ore_algebra.md b/apn/lean/docs/ore_algebra/ore_algebra.md deleted file mode 100644 index 28e2de11..00000000 --- a/apn/lean/docs/ore_algebra/ore_algebra.md +++ /dev/null @@ -1,1709 +0,0 @@ - - -# ore_algebra (Sage package) - -Ore algebra -============ - -https://github.com/mkauers/ore_algebra/ - -Description ------------ - -A Sage implementation of Ore algebras, Ore polynomials, and differentially -finite functions - -Main features for the most common algebras include basic arithmetic and actions; -gcrd and lclm; D-finite closure properties; creative telescoping; natural -transformations between related algebras; guessing; desingularization; solvers -for polynomials, rational functions and (generalized) power series. Univariate -differential operators also support the numerical computation of analytic -solutions with rigorous error bounds and related features. - - - -## Module `ore_algebra` — constructing Ore algebras - -Ore algebras - -The ``ore_algebra`` package provides functionality for doing computations with Ore polynomials. - -Ore polynomials are operators which can be used to describe special functions or combinatorial -sequences. Typical examples are linear differential operators with polynomial coefficients. - -Ore polynomials are elements of Ore algebras. Ore algebras are ring objects created by the -function ``OreAlgebra`` as described below. - -Depending on the particular parent algebra, Ore polynomials may support different functionality. -For example, for Ore polynomials representing recurrence operators, there is a method for -computing interlacing operators, an operation which does not make sense for differential operators. - -The typical user will only need two functions defined in the package: - - * ``OreAlgebra`` -- for creating a new Ore algebra object. - * ``guess`` -- for fitting an Ore polynomial to a given set of data. - -Ore polynomials are created using ``OreAlgebra`` objects, and most of the functionality for -doing calculations with Ore polynomials is available in the methods attached to them. - -For examples and further information, see the docstring of ``OreAlgebra`` below, or the -tutorial paper *Ore Polynomials in Sage* by the authors. - - -AUTHOR: - -- Manuel Kauers, Maximilian Jaroschek, Fredrik Johansson (2013-06-15) - -### `OreAlgebra` - -``` -An Ore algebra is a noncommutative polynomial ring whose elements are -interpreted as operators. - -An Ore algebra has the form `A=R[\partial_1,\partial_2,\dots,\partial_n]` -where `R` is an integral domain and `\partial_1,\dots,\partial_n` are -indeterminates. For each of them, there is an associated automorphism -`\sigma:R\\rightarrow R` and a skew-derivation `\delta:R\\rightarrow R` -satisfying `\delta(a+b)=\delta(a)+\delta(b)` and -`\delta(ab)=\delta(a)b+\sigma(a)\delta(b)` for all `a,b\in R`. - -The generators `\partial_i` commute with each other, but not with elements -of the base ring `R`. Instead, we have the commutation rules `\partial u = -\sigma(u) \partial + \delta(u)` for all `u\in R`. - -The base ring `R` must be suitable according to the following definition: -`ZZ`, `QQ`, `GF(p)` for primes `p`, and finite algebraic extensions of `QQ` -are suitable, and if `R` is suitable then so are `R[x]`, `R[x_1,x_2,...]` -and `Frac(R)`. It is assumed that all the `\sigma` leave ``R.base_ring()`` fixed -and all the `\delta` map ``R.base_ring()`` to zero. - -A typical example of an Ore algebra is the ring of linear differential -operators with rational function coefficients in one variable, -e.g. `A=QQ[x][D]`. Here, `\sigma` is the identity and `\delta` is the -standard derivation `d/dx`. - -To create an Ore algebra, supply a suitable base ring and one or more -generators. Each generator has to be given in form of a triple -``(name,sigma,delta)`` where ``name`` is the desired name of the variable -(used for printout), ``sigma`` and ``delta`` are arbitrary callable objects -which applied to the base ring return other base ring elements in accordance -with the relevant laws. It is not checked whether they do. - -:: - - sage: from ore_algebra import * - - sage: R. = QQ['x'] - sage: K = R.fraction_field() - - # This creates an Ore algebra of linear differential operators - sage: A. = OreAlgebra(K, ('D', lambda p: p, lambda p: p.derivative(x))) - sage: A - Univariate Ore algebra in D over Fraction Field of Univariate Polynomial Ring in x over Rational Field - - # This creates an Ore algebra of linear recurrence operators - sage: A. = OreAlgebra(K, ('S', lambda p: p(x+1), lambda p: K.zero())) - sage: A - Univariate Ore algebra in S over Fraction Field of Univariate Polynomial Ring in x over Rational Field - -Instead of a callable object for `\sigma` and `\delta`, also a dictionary can -be supplied which for every generator of the base ring specifies the desired -image. If some generator is not in the dictionary, it is understood that -`\sigma` acts as identity on it, and that `\delta` maps it to zero. - -:: - - sage: U. = ZZ['x', 'y'] - - # here, the base ring represents the differential field QQ(x, e^x) - sage: A. = OreAlgebra(U, ('D', {}, {x:1, y:y})) - - # here, the base ring represents the difference field QQ(x, 2^x) - sage: B. = OreAlgebra(U, ('S', {x:x+1, y:2*y}, {})) - - # here too, but the algebra's generator represents the forward difference instead of the shift - sage: C. = OreAlgebra(U, ('Delta', {x:x+1, y:2*y}, {x:1, y:y})) - -For the most frequently needed operators, the constructor accepts their -specification as a string only, without explicit statement of sigma or -delta. The string has to start with one of the letters listed in the -following table. The remainder of the string has to be the name of one -of the generators of the base ring. The operator will affect this generator -and leave the others untouched. - - ============= ======================= ================ ============= - Prefix Operator `\sigma` `\delta` - ============= ======================= ================ ============= - C Commutative variable `\{\}` `\{\}` - D Standard derivative `\{\}` `\{x:1\}` - S Standard shift `\{x:x+1\}` `\{\}` - \u0394, F Forward difference `\{x:x+1\}` `\{x:1\}` - \u03B8, T, E Euler derivative `\{\}` `\{x:x\}` - Q q-shift `\{x:q*x\}` `\{\}` - J Jackson's q-derivative `\{x:q*x\}` `\{x:1\}` - ============= ======================= ================ ============= - -In the case of C, the suffix need not be a generator of the ground field but -may be an arbitrary string. In the case of Q and J, either the base ring has -to contain an element `q`, or the base ring element to be used instead has to -be supplied as optional argument. - -:: - - sage: R. = QQ['x', 'y'] - sage: A = OreAlgebra(R, 'Dx') # This creates an Ore algebra of differential operators - sage: A == OreAlgebra(R, ('Dx', {}, {x:1})) - True - sage: A == OreAlgebra(R, ('Dx', {}, {y:1})) # the Dx in A acts on x, not on y - False - - # This creates an Ore algebra of linear recurrence operators - sage: A = OreAlgebra(R, 'Sx') - sage: A == OreAlgebra(R, ('Sx', {x:x+1}, {})) - True - sage: A == OreAlgebra(R, ('Sx', {y:y+1}, {})) # the Sx in A acts on x, not on y - False - sage: OreAlgebra(R, 'Qx', q=2) - Univariate Ore algebra in Qx over Multivariate Polynomial Ring in x, y over Rational Field - -A generator can optionally be extended by a vector `(w_0,w_1,w_2)` of -base ring elements which encodes the product rule for the generator: -`D(u*v) == w_0*u*v + w_1*(D(u)*v + u*D(v)) + w_2*D(u)*D(v)`. This data -is needed in the computation of symmetric products. - -Ore algebras support coercion from their base rings. Furthermore, an Ore -algebra `A` knows how to coerce commutative polynomials `p` to elements of -`A` if the generators of the parent of `p` have the same names as the -generators of `A`, and the base ring of the parent of `p` admits a coercion -to the base ring of `A`. The ring of these polynomials is called the -associated commutative algebra of `A`, and it can be obtained by calling -``A.associated_commutative_algebra()``. - -Elements of Ore algebras are called Ore operators. They can be constructed -from the same data from which also elements of the associated commutative -algebra can be constructed. - -The conversion from data to an Ore operator is equivalent to the conversion -from the given data to an element of the associated commutative algebra, and -from there to an Ore operator. This has the consequence that possible implicit -information about multiplication order may be lost, for example when generating -operators from strings: - -:: - - sage: A = OreAlgebra(QQ['x'], 'Dx') - sage: A("Dx*x") - x*Dx - sage: A("Dx")*A("x") - x*Dx + 1 - -A safer way of creating operators is via a list of coefficients. These are then -always interpreted as standing to the left of the respective algebra generator monomial. - -:: - - sage: R. = QQ['x'] - sage: A. = OreAlgebra(R, 'Dx') - sage: A([x^2+1, 5*x-7, 7*x+18]) - (7*x + 18)*Dx^2 + (5*x - 7)*Dx + x^2 + 1 - sage: (7*x + 18)*Dx^2 + (5*x - 7)*Dx + x^2 + 1 - (7*x + 18)*Dx^2 + (5*x - 7)*Dx + x^2 + 1 - sage: _^2 - (49*x^2 + 252*x + 324)*Dx^4 + (70*x^2 + 180*x)*Dx^3 + (14*x^3 + 61*x^2 + 49*x + 216)*Dx^2 + (10*x^3 + 14*x^2 + 107*x - 49)*Dx + x^4 + 12*x^2 + 37 - - sage: R. = QQ['x'] - sage: A. = OreAlgebra(QQ['x'], 'Sx') - sage: A([x^2+1, 5*x-7, 7*x+18]) - (7*x + 18)*Sx^2 + (5*x - 7)*Sx + x^2 + 1 - sage: (7*x + 18)*Sx^2 + (5*x - 7)*Sx + x^2 + 1 - (7*x + 18)*Sx^2 + (5*x - 7)*Sx + x^2 + 1 - sage: _^2 - (49*x^2 + 350*x + 576)*Sx^4 + (70*x^2 + 187*x - 121)*Sx^3 + (14*x^3 + 89*x^2 + 69*x + 122)*Sx^2 + (10*x^3 - 4*x^2 + x - 21)*Sx + x^4 + 2*x^2 + 1 - -It is possible to bypass the check that the base ring is suitable, but doing so -may lead to mathematically incorrect results. Only use this if you know exactly -what you are doing! :: - - sage: R. = SR[] - sage: Dop. = OreAlgebra(R, check_base_ring=False) - sage: (Dx - pi*x)^2 - Dx^2 - 2*pi*x*Dx + pi^2*x^2 - pi -``` - - -### `DifferentialOperators` - -``` -Shorthand to construct an Ore algebra of differential operators. - -Return an Ore algebra of differential operators with polynomial -coefficients, along with objects representing, x and d/dx. - -.. SEEALSO:: :func:`OreAlgebra` - -INPUT: - -* ``base`` (default ``QQ``) - base ring of the polynomial coefficients -* ``var`` (default ``x``) - variable name - -EXAMPLES:: - - sage: from ore_algebra import * - sage: Dops, x, Dx = DifferentialOperators() - sage: Dops - Univariate Ore algebra in Dx over Univariate Polynomial Ring in x over - Rational Field - sage: x*Dx + 1 - x*Dx + 1 - - sage: DifferentialOperators(GF(2), 't') - (Univariate Ore algebra in Dt over Univariate Polynomial Ring in t over - Finite Field of size 2 (...), - t, Dt) -``` - - -## Module `ore_algebra.guessing` - -Guessing tools - -TESTS:: - - sage: from ore_algebra import OreAlgebra, guess - sage: guess([SR(1/(i+1)) for i in range(10)], OreAlgebra(QQ['n'], 'Sn')) - (-n - 2)*Sn + n + 1 - -### `guess_rec` - -``` -Shortcut for ``guess`` applied with an Ore algebra of shift operators in `S` over `K[n]` -where `K` is the parent of ``data[0]``. - -See the docstring of ``guess`` for further information. -``` - - -### `guess_deq` - -``` -Shortcut for ``guess`` applied with an Ore algebra of differential operators in `D` over `K[x]` -where `K` is the parent of ``data[0]``. - -See the docstring of ``guess`` for further information. -``` - - -### `guess_qrec` - -``` -Shortcut for ``guess`` applied with an Ore algebra of `q`-recurrence operators in `Q` over `K[qn]` -where `K` is the parent of `q`. - -See the docstring of ``guess`` for further information. -``` - - -### `guess` - -``` -Searches for an element of the algebra which annihilates the given data. - -INPUT: - -- ``data`` -- a list of elements of the algebra's base ring's base ring `K` (or at least - of objects which can be casted into this ring). If ``data`` is a string, it is assumed - to be the name of a text file which contains the terms, one per line, encoded in a way - that can be interpreted by the element constructor of `K`. -- ``algebra`` -- a univariate Ore algebra over a univariate polynomial ring whose - generator is the standard derivation, the standard shift, the forward difference, - a q-shift, or a commutative variable. - -Optional arguments: - -- ``cut`` -- if `N` is the minimum number of terms needed for some particular - choice of order and degree, and if ``len(data)`` is more than ``N+cut``, - use ``data[:N+cut]`` instead of ``data``. This must be a nonnegative integer - or ``None``. Default: ``None``. -- ``ensure`` -- if `N` is the minimum number of terms needed for some particular - choice of order and degree, and if ``len(data)`` is less than ``N+ensure``, - raise an error. This must be a nonnegative integer. Default: 0. -- ``ncpus`` -- number of processors to be used. Default: 1. -- ``order`` -- bounds the order of the operators being searched for. - Default: infinity. -- ``min_order`` -- smallest order to be considered in the search. The output - may nevertheless have lower order than this bound. Default: 1 -- ``degree`` -- bounds the degree of the operators being searched for. - The method may decide to overrule this setting if it thinks this may speed up - the calculation. Default: infinity. -- ``min_degree`` -- smallest degree to be considered in the search. The output - may nevertheless have lower degree than this bound. Default: 0 -- ``path`` -- a list of pairs `(r, d)` specifying which orders and degrees - the method should attempt. If this value is equal to ``None`` (default), a - path is chosen which examines all the `(r, d)` which can be tested with the - given amount of data. -- ``solver`` -- function to be used for computing the right kernel of a matrix - with elements in `K`. -- ``infolevel`` -- an integer specifying the level of details of progress - reports during the calculation. -- ``method`` -- either "linalg" (for linear algebra) or "hp" (for Hermite-Pade) or "automatic" - (for the default choice), or a callable with the specification of a raw guesser. - -OUTPUT: - -- An element of ``algebra`` which annihilates the given ``data``. - -An error is raised if no such element is found. - -.. NOTE:: - - - This method is designed to find equations for D-finite objects. It - may exhibit strange behaviour for objects which are holonomic but not - D-finite. - - When the generator of the algebra is a commutative variable, the - method searches for algebraic equations. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: rec = guess([(2*i+1)^15 * (1 + 2^i + 3^i)^2 for i in range(1000)], OreAlgebra(ZZ['n'], 'Sn')) # long time (2.9 s) - sage: rec.order(), rec.degree() # long time - (6, 90) - sage: R. = QQ['t'] - sage: rec = guess([1/(i+t) + t^i for i in range(100)], OreAlgebra(R['n'], 'Sn')) - sage: rec - ((-t + 1)*n^2 + (-2*t^2 - t + 2)*n - t^3 - 2*t^2)*Sn^2 + ((t^2 - 1)*n^2 + (2*t^3 + 3*t^2 - 2*t - 1)*n + t^4 + 3*t^3 + t^2 - t)*Sn + (-t^2 + t)*n^2 + (-2*t^3 + t)*n - t^4 - t^3 + t^2 - - sage: R. = OreAlgebra(ZZ['x']) - sage: cat = [binomial(2*n,n) // (n+1) for n in range(10)] - sage: guess(cat, R) - -x*C^2 + C - 1 -``` - - -### `guess_raw` - -``` -Guesses recurrence or differential equations for a given sample of terms. - -INPUT: - -- ``data`` -- list of terms -- ``A`` -- an Ore algebra of recurrence operators, differential operators, - or q-differential operators. -- ``order`` -- maximum order of the sought operators -- ``degree`` -- maximum degree of the sought operators -- ``lift`` (optional) -- a function to be applied to the terms in ``data`` - prior to computation -- ``solver`` (optional) -- a function to be used to compute the nullspace - of a matrix with entries in the base ring of the base ring of ``A`` -- ``cut`` (optional) -- if `N` is the minimum number of terms needed for - the the specified order and degree and ``len(data)`` is more than ``N+cut``, - use ``data[:N+cut]`` instead of ``data``. This must be a nonnegative integer - or ``None``. -- ``ensure`` (optional) -- if `N` is the minimum number of terms needed - for the specified order and degree and ``len(data)`` is less than ``N+ensure``, - raise an error. This must be a nonnegative integer. -- ``infolevel`` (optional) -- an integer indicating the desired amount of - progress report to be printed during the calculation. Default: 0 (no output). - -OUTPUT: - -A basis of the ``K``-vector space of all the operators `L` in ``A`` of order -at most ``order`` and degree at most ``degree`` such that `L` applied to -``data`` gives an array of zeros. (resp. `L` applied to the truncated power -series with ``data`` as terms gives the zero power series) - -An error is raised in the following situations: - -* the algebra ``A`` has more than one generator, or its unique generator - is neither a standard shift nor a q-shift nor a standard derivation. -* ``data`` contains some item which does not belong to ``K``, even after - application of ``lift`` -* if the condition on ``ensure`` is violated. -* if the linear system constructed by the method turns out to be - underdetermined for some other reason, e.g., because too many linear - constraints happen to be trivial. - -ALGORITHM: - -Ansatz and linear algebra. - -.. NOTE:: - - This is a low-level method. Don't call it directly unless you know what you - are doing. In usual applications, the right method to call is ``guess``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: K = GF(1091); R. = K['n']; A = OreAlgebra(R, 'Sn') - sage: data = [(5*n+3)/(3*n+4)*fibonacci(n)^3 for n in range(200)] - sage: guess_raw(data, A, order=5, degree=3, lift=K) - [(n^3 + 546*n^2 + 588*n + 786)*Sn^5 + (356*n^3 + 717*n^2 + 381*n + 449)*Sn^4 + (8*n^3 + 569*n^2 + 360*n + 214)*Sn^3 + (31*n^3 + 600*n^2 + 784*n + 287)*Sn^2 + (1078*n^3 + 1065*n^2 + 383*n + 466)*Sn + 359*n^3 + 173*n^2 + 503, (n^3 + 1013*n^2 + 593*n + 754)*Sn^5 + (797*n^3 + 56*n^2 + 7*n + 999)*Sn^4 + (867*n^3 + 1002*n^2 + 655*n + 506)*Sn^3 + (658*n^3 + 834*n^2 + 1036*n + 899)*Sn^2 + (219*n^3 + 479*n^2 + 476*n + 800)*Sn + 800*n^3 + 913*n^2 + 280*n] -``` - - -### `guess_hp` - -``` -Guesses differential equations or algebraic equations for a given sample of terms. - -INPUT: - -- ``data`` -- list of terms -- ``A`` -- an Ore algebra of differential operators or ordinary polynomials. -- ``order`` -- maximum order of the sought operators -- ``degree`` -- maximum degree of the sought operators -- ``lift`` (optional) -- a function to be applied to the terms in ``data`` - prior to computation -- ``cut`` (optional) -- if `N` is the minimum number of terms needed for - the the specified order and degree and ``len(data)`` is more than ``N+cut``, - use ``data[:N+cut]`` instead of ``data``. This must be a nonnegative integer - or ``None``. -- ``ensure`` (optional) -- if `N` is the minimum number of terms needed - for the specified order and degree and ``len(data)`` is less than ``N+ensure``, - raise an error. This must be a nonnegative integer. -- ``infolevel`` (optional) -- an integer indicating the desired amount of - progress report to be printed during the calculation. Default: 0 (no output). - -OUTPUT: - -A basis of the ``K``-vector space of all the operators `L` in ``A`` of order -at most ``order`` and degree at most ``degree`` such that `L` applied to -the truncated power series with ``data`` as terms gives the zero power series. - -An error is raised in the following situations: - -* the algebra ``A`` has more than one generator, or its unique generator - is neither a standard derivation nor a commutative variable. -* ``data`` contains some item which does not belong to ``K``, even after - application of ``lift`` -* if the condition on ``ensure`` is violated. - -ALGORITHM: - -Hermite-Pade approximation. - -.. NOTE:: - - This is a low-level method. Don't call it directly unless you know what you - are doing. In usual applications, the right method to call is ``guess``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: from ore_algebra.guessing import guess_hp - sage: K = GF(1091); R. = K['x']; - sage: data = [binomial(2*n, n)*fibonacci(n)^3 for n in range(2000)] - sage: guess_hp(data, OreAlgebra(R, 'Dx'), order=4, degree=4, lift=K) - [(x^4 + 819*x^3 + 136*x^2 + 17*x + 635)*Dx^4 + (14*x^3 + 417*x^2 + 952*x + 605)*Dx^3 + (598*x^2 + 497*x + 99)*Dx^2 + (598*x + 794)*Dx + 893] - sage: len(guess_hp(data, OreAlgebra(R, 'C'), order=16, degree=64, lift=K)) - 1 -``` - - -### `guess_mult` - -``` -Searches for elements of the algebra which annihilates the given data. - -INPUT: - -- ``data`` -- a nested list of elements of the algebra's base ring's base ring `K` (or at least - of objects which can be casted into this ring). - The depth of the nesting must match the number of generators of the algebra. -- ``algebra`` -- an Ore algebra over a polynomial ring all of whose generators are - the standard derivation, the standard shift, or a q-shift. - -Optional arguments: - -- ``cut`` -- if `N` is the minimum number of terms needed for some particular - choice of order and degree, and if ``len(data)`` is more than ``N+cut``, - use ``data[:N+cut]`` instead of ``data``. This must be a nonnegative integer - or ``None``. Default: 100. -- ``ensure`` -- if `N` is the minimum number of terms needed for some particular - choice of order and degree, and if ``len(data)`` is less than ``N+ensure``, - raise an error. This must be a nonnegative integer. Default: 0. -- ``order`` -- maximum degree of the algebra generators in the sought operators. - Alternatively: a list or tuple specifying individual degree bounds for each - generator of the algebra. Default: 2 -- ``degree`` -- maximum total degree of the polynomial coefficients in the sought - operators. Default: 3 -- ``point_filter`` -- a callable such that index tuples of data array for which - the callable returns 'False' will not be used. Default: None (everything allowed). -- ``term_filter`` -- a callable such that operators containing power products of - the algebra generators for which the callable returns 'False' are excluded. - Default: None (everything allowed). -- ``solver`` -- function to be used for computing the right kernel of a matrix - with elements in `K`. -- ``infolevel`` -- an integer specifying the level of details of progress - reports during the calculation. - -OUTPUT: - -- The left ideal of ``algebra`` generated by all the operators of the specified order and degree - that annihilate the given ``data``. It may be the zero ideal. - -.. NOTE:: - - This method is designed to find equations for D-finite objects. It may - exhibit strange behaviour for objects which are holonomic but not - D-finite. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: from ore_algebra.guessing import guess_mult - sage: data = [[binomial(n,k) for n in range(10)] for k in range(10)] - sage: guess_mult(data, OreAlgebra(ZZ['n','k'], 'Sn', 'Sk'), order=1, degree=0) - Left Ideal (Sn*Sk - Sn - 1) of Multivariate Ore algebra in Sn, Sk over Fraction Field of Multivariate Polynomial Ring in n, k over Integer Ring - sage: guess_mult(data, OreAlgebra(ZZ['x','y'], 'Dx', 'Dy'), order=1, degree=1) - Left Ideal ((x + 1)*Dx + (-y)*Dy) of Multivariate Ore algebra in Dx, Dy over Fraction Field of Multivariate Polynomial Ring in x, y over Integer Ring - sage: guess_mult(data, OreAlgebra(ZZ['n','y'], 'Sn', 'Dy'), order=1, degree=1) - Left Ideal ((-y + 1)*Sn*Dy - Sn + (-y)*Dy - 1, (-n - 1)*Sn + y*Dy - n, (-y + 1)*Sn - y) of Multivariate Ore algebra in Sn, Dy over Fraction Field of Multivariate Polynomial Ring in n, y over Integer Ring - sage: guess_mult(data, OreAlgebra(ZZ['x','k'], 'Dx', 'Sk'), order=1, degree=1) - Left Ideal (Dx*Sk + (-x - 1)*Dx - 1, x*Dx*Sk + (x + 1)*Dx + (-k)*Sk - x, (x + 1)*Dx - k, (x + 1)*Dx*Sk + (-k - 1)*Sk) of Multivariate Ore algebra in Dx, Sk over Fraction Field of Multivariate Polynomial Ring in x, k over Integer Ring -``` - - -### `guess_mult_raw` - -``` -Low-level multivariate guessing function. Do not call this method unless you know what you are doing. -In most situations, you will want to call the function `guess` instead. - -INPUT: - -- `data` -- a nested list of elements of C -- `terms` -- a list of pairs of tuples (u, v) specifying exponent vectors u, v representing terms x^u D^v -- `points` -- a list of tuples specifying indices of the data array -- `power` -- a list of functions f mapping triples (n, u, v) of nonnegative integers to elements of C -- `A` -- a list of functions mapping triples (n, u, v) to integers -- `B` -- a list of functions mapping triples (n, u, v) to integers - -OUTPUT: - -A list of vectors generating the space of all vectors in C^len(terms) for which -all(sum(prod(f[i][A[i][n[i],u[i],v[i]]]*a[B[i][n[i],u[i],v[i]]] for i in range(len(A))) -for u,v in terms) == 0 for n in points) - -SIDE EFFECT: - -Elements of the list `points` which lead to a zero equation will be discarded. -``` - -### `UnivariateOreOperatorOverUnivariateRing.polynomial_solutions` - -``` -Computes the polynomial solutions of this operator. - -INPUT: - -- ``rhs`` (optional) -- a list of base ring elements -- ``degree`` (optional) -- bound on the degree of interest. -- ``solver`` (optional) -- a callable for computing the right kernel - of a matrix over the base ring's base ring. - -OUTPUT: - -A list of tuples `(p, c_0,...,c_r)` such that `self(p) == c_0*rhs[0] + ... + c_r*rhs[r]`, -where `p` is a polynomial and `c_0,...,c_r` are constants. - -.. NOTE:: - - - Even if no ``rhs`` is given, the output will be a list of tuples ``[(p1,), (p2,),...]`` - and not just a list of plain polynomials. - - If no ``degree`` is given, a basis of all the polynomial solutions is returned. - This feature may not be implemented for all algebras. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['n']; A. = OreAlgebra(R, 'Sn') - sage: L = 2*Sn^2 + 3*(n-7)*Sn + 4 - sage: L.polynomial_solutions((n^2+4*n-8, 4*n^2-5*n+3)) - [(-70*n + 231, 242, -113)] - sage: L(-70*n + 231) - -210*n^2 + 1533*n - 2275 - sage: 242*(n^2+4*n-8) - 113*(4*n^2-5*n+3) - -210*n^2 + 1533*n - 2275 - - sage: R. = ZZ['x']; A. = OreAlgebra(R, 'Dx') - sage: L = (x*Dx - 19).lclm( x*Dx - 4 ) - sage: L.polynomial_solutions() - [(x^4,), (x^19,)] -``` - - -### `UnivariateOreOperatorOverUnivariateRing.rational_solutions` - -``` -Computes the rational solutions of this operator. - -INPUT: - -- ``rhs`` (optional) -- a list of base ring elements -- ``denominator`` (optional) -- bound on the degree of interest. -- ``degree`` (optional) -- bound on the degree of interest. -- ``solver`` (optional) -- a callable for computing the right kernel - of a matrix over the base ring's base ring. - -OUTPUT: - -A list of tuples `(r, c_0,...,c_r)` such that `self(r) == c_0*rhs[0] + ... + c_r*rhs[r]`, -where `r` is a rational function and `c_0,...,c_r` are constants. - -.. NOTE:: - - - Even if no ``rhs`` is given, the output will be a list of tuples ``[(p1,), (p2,),...]`` - and not just a list of plain rational functions. - - If no ``denominator`` is given, a basis of all the rational solutions is returned. - This feature may not be implemented for all algebras. - - If no ``degree`` is given, a basis of all the polynomial solutions is returned. - This feature may not be implemented for all algebras. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x']; A. = OreAlgebra(R, 'Dx') - sage: L = ((x+3)*Dx + 2).lclm(x*Dx + 3).symmetric_product((x+4)*Dx-2) - sage: L.rational_solutions() - [((-x^2 - 8*x - 16)/x^3,), - ((-x^5 + 96*x^3 + 584*x^2 + 1344*x + 1152)/(x^5 + 6*x^4 + 9*x^3),)] - sage: L.rational_solutions((1, x)) - [((x^2 + 8*x + 16)/(x^2 + 6*x + 9), 0, 0), - ((x^5 + 7*x^4 + 2*x^3 - 73*x^2 - 168*x - 144)/(x^5 + 6*x^4 + 9*x^3), 0, 0), - ((-2*x - 7)/(x^2 + 6*x + 9), 288, 42)] - sage: L(_[0][0]) == _[0][1] + _[0][2]*x - True - - sage: (x*(x*Dx-5)).rational_solutions([1]) - [(-x^5, 0), (1/x, -6)] - - sage: R. = ZZ['n']; A. = OreAlgebra(R, 'Sn'); - sage: L = ((n+3)*Sn - n).lclm((2*n+5)*Sn - (2*n+1)) - sage: L.rational_solutions() - [(-1/(n^3 + 3*n^2 + 2*n),), - ((-n^3 + n^2 + 6*n + 3)/(4*n^5 + 20*n^4 + 35*n^3 + 25*n^2 + 6*n),)] - - sage: L = (2*n^2 - n - 2)*Sn^2 + (-n^2 - n - 1)*Sn + n^2 - 14 - sage: y = (-n + 1)/(n^2 + 2*n - 2) - sage: L.rational_solutions((L(y),)) - [((n - 1)/(n^2 + 2*n - 2), -1)] -``` - - -## Selected operator methods - - -### `UnivariateDifferentialOperatorOverUnivariateRing.to_S` (differential operators (D)) - -``` -Return a recurrence operator annihilating the coefficient sequence of -every power series (about the origin) annihilated by ``self``. - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_S()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - the standard shift with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: A. = OreAlgebra(R, 'Dx') - sage: R2. = ZZ['n'] - sage: A2. = OreAlgebra(R2, 'Sn') - sage: (Dx - 1).to_S(A2) - (n + 1)*Sn - 1 - sage: ((1+x)*Dx^2 + Dx).to_S(A2) - (n^2 + n)*Sn + n^2 - sage: ((x^3+x^2-x)*Dx + (x^2+1)).to_S(A2) - (-n - 1)*Sn^2 + (n + 1)*Sn + n + 1 - sage: ((x+1)*Dx^3 + Dx^2).to_S(A2) - (n^3 - n)*Sn + n^3 - 2*n^2 + n -``` - - -### `UnivariateDifferentialOperatorOverUnivariateRing.to_T` (differential operators (D)) - -``` -Rewrite ``self`` in terms of the eulerian derivation `x*d/dx`. - -If the base ring of the target algebra is not a field, the -operator returned by the method may not correspond exactly to -``self``, but only to a suitable left-multiple by a term `x^k`. - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_T()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - an euler derivation with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: R2. = ZZ['y'] - sage: A. = OreAlgebra(R, 'Dx') - sage: (Dx^4).to_T(OreAlgebra(R2, 'Ty')) - Ty^4 - 6*Ty^3 + 11*Ty^2 - 6*Ty - sage: (Dx^4).to_T('Tx').to_D(A) - x^4*Dx^4 - sage: _.to_T('Tx') - Tx^4 - 6*Tx^3 + 11*Tx^2 - 6*Tx -``` - - -### `UnivariateDifferentialOperatorOverUnivariateRing.annihilator_of_integral` (differential operators (D)) - -``` -Return an operator `L` which annihilates all the indefinite integrals `\int f` -where `f` runs through the functions annihilated by ``self``. - -The output operator is not necessarily of smallest possible order. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: A. = OreAlgebra(R, 'Dx') - sage: ((x-1)*Dx - 2*x).annihilator_of_integral() - (x - 1)*Dx^2 - 2*x*Dx - sage: _.annihilator_of_associate(Dx) - (x - 1)*Dx - 2*x -``` - - -### `UnivariateDifferentialOperatorOverUnivariateRing.annihilator_of_composition` (differential operators (D)) - -``` -Return an operator `L` which annihilates all the functions `f(a(x))` where -`f` runs through the functions annihilated by ``self``, and, optionally, -a map from the quotient by ``self`` to the quotient by `L` commuting -with the composition by `a`. - -The output operator `L` is not necessarily of smallest possible order. - -INPUT: - -- ``a`` -- either an element of the base ring of the parent of ``self``, - or an element of an algebraic extension of this ring. -- ``solver`` (optional) -- a callable object which applied to a matrix - with polynomial entries returns its kernel. -- ``with_transform`` (optional) -- if `True`, also return a - transformation map between the quotients - -OUTPUT: - -- ``L`` -- an Ore operator such that for all ``f`` annihilated by - ``self``, ``L`` annihilates ``f \circ a``. -- ``conv`` -- a function which takes as input an Ore operator ``P`` and - returns an Ore operator ``Q`` such that for all functions ``f`` - annihilated by ``self``, ``P(f)(a(x)) = Q(f \circ a)(x)``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: K. = R.fraction_field()['y'] - sage: K. = R.fraction_field().extension(y^3 - x^2*(x+1)) - sage: A. = OreAlgebra(R, 'Dx') - sage: (x*Dx-1).annihilator_of_composition(y) # ann for x^(2/3)*(x+1)^(1/3) - (3*x^2 + 3*x)*Dx - 3*x - 2 - sage: (x*Dx-1).annihilator_of_composition(y + 2*x) # ann for 2*x + x^(2/3)*(x+1)^(1/3) - (3*x^3 + 3*x^2)*Dx^2 - 2*x*Dx + 2 - sage: (Dx - 1).annihilator_of_composition(y) # ann for exp(x^(2/3)*(x+1)^(1/3)) - (-243*x^6 - 810*x^5 - 999*x^4 - 540*x^3 - 108*x^2)*Dx^3 + (-162*x^3 - 270*x^2 - 108*x)*Dx^2 + (162*x^2 + 180*x + 12)*Dx + 243*x^6 + 810*x^5 + 1080*x^4 + 720*x^3 + 240*x^2 + 32*x - -If composing with a rational function, one can also compute the -transformation map between the quotients.:: - - sage: L = x*Dx^2 + 1 - sage: LL, conv = L.annihilator_of_composition(x+1, with_transform=True) - sage: print(LL) - (x + 1)*Dx^2 + 1 - sage: print(conv(Dx)) - Dx - sage: print(conv(x*Dx)) - (x + 1)*Dx - sage: print(conv(L)) - 0 - sage: LL, conv = L.annihilator_of_composition(1/x, with_transform=True) - sage: print(LL) - -x^3*Dx^2 - 2*x^2*Dx - 1 - sage: print(conv(Dx)) - -x^2*Dx - sage: print(conv(x*Dx)) - -x*Dx - sage: print(conv(conv(x*Dx))) # identity since 1/1/x = x - x*Dx - sage: LL, conv = L.annihilator_of_composition(1+x^2, with_transform=True) - sage: print(LL) - (-x^3 - x)*Dx^2 + (x^2 + 1)*Dx - 4*x^3 - sage: print(conv(Dx)) - 1/(2*x)*Dx - sage: print(conv(x*Dx)) - ((x^2 + 1)/(2*x))*Dx -``` - - -### `UnivariateDifferentialOperatorOverUnivariateRing.power_series_solutions` (differential operators (D)) - -``` -Compute the first few terms of the power series solutions of this operator. - -The method raises an error if Sage does not know how to factor -univariate polynomials over the base ring's base ring. - -The base ring has to have characteristic zero. - -INPUT: - -- ``n`` -- minimum number of terms to be computed - -OUTPUT: - -A list of power series of the form `x^\alpha + ...` with pairwise distinct -exponents `\alpha` and coefficients in the base ring's base ring's fraction field. -All expansions are computed up to order `k` where `k` is obtained by adding the -maximal `\alpha` to the maximum of `n` and the order of ``self``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: A. = OreAlgebra(R, 'Dx') - sage: ((1-x)*Dx - 1).power_series_solutions(10) # geometric series - [1 + x + x^2 + x^3 + x^4 + x^5 + x^6 + x^7 + x^8 + O(x^9)] - sage: (Dx - 1).power_series_solutions(5) # exp(x) - [1 + x + 1/2*x^2 + 1/6*x^3 + O(x^4)] - sage: (Dx^2 - Dx + x).power_series_solutions(5) # a 2nd order equation - [x + 1/2*x^2 + 1/6*x^3 - 1/24*x^4 + O(x^5), 1 - 1/6*x^3 - 1/24*x^4 + O(x^5)] - sage: (2*x*Dx - 1).power_series_solutions(5) # sqrt(x) is not a power series - [] -``` - - -### `UnivariateDifferentialOperatorOverUnivariateRing.generalized_series_solutions` (differential operators (D)) - -``` -Return the generalized series solutions of this operator. - -These are solutions of the form - - `\exp(\int_0^x \frac{p(t^{-1/s})}t dt)*q(x^{1/s},\log(x))` - -where - -* `s` is a positive integer (the object's "ramification") -* `p` is in `K[x]` (the object's "exponential part") -* `q` is in `K[[x]][y]` with `x\nmid q` unless `q` is zero (the object's "tail") -* `K` is some algebraic extension of the base ring's base ring. - -An operator of order `r` has exactly `r` linearly independent solutions of this form. -This method computes them all, unless the flags specified in the arguments rule out some -of them. - -At present, the method only works for operators where the base ring's base ring is either -QQ or a number field (i.e., no finite fields, no formal parameters). - -INPUT: - -- ``n`` (default: 5) -- minimum number of terms in the series expansions to be computed - in addition to those needed to separate all solutions from each other. -- ``base_extend`` (default: ``True``) -- whether or not the coefficients of the solutions may - belong to an algebraic extension of the base ring's base ring. -- ``ramification`` (default: ``True``) -- whether or not the exponential parts of the solutions - may involve fractional exponents. -- ``exp`` (default: ``True``) -- set this to ``False`` if you only want solutions that have no - exponential part (viz `\deg(p)\leq0`). If set to a positive rational number `\alpha`, - the method returns all those solutions whose exponential part involves only terms `x^{-i/r}` - with `i/r<\alpha`. - -OUTPUT: - -- a list of ``ContinuousGeneralizedSeries`` objects forming a fundamental system for this operator. - -.. NOTE:: - - - Different solutions may require different algebraic extensions. Thus in the list returned - by this method, the coefficient fields of different series typically do not coincide. - - If a solution involves an algebraic extension of the coefficient field, then all its - conjugates are solutions, too. But only one representative is listed in the output. - -ALGORITHM: - -- Ince, Ordinary Differential Equations, Chapters 16 and 17 -- Kauers/Paule, The Concrete Tetrahedron, Section 7.3 - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = QQ['x']; A. = OreAlgebra(R, 'Dx') - sage: L = (6+6*x-3*x^2) - (10*x-3*x^2-3*x^3)*Dx + (4*x^2-6*x^3+2*x^4)*Dx^2 - sage: L.generalized_series_solutions() - [x^3*(1 + 3/2*x + 7/4*x^2 + 15/8*x^3 + 31/16*x^4 + O(x^5)), x^(1/2)*(1 + 3/2*x + 7/4*x^2 + 15/8*x^3 + 31/16*x^4 + O(x^5))] - sage: list(map(L, _)) - [0, 0] - - sage: L = (1-24*x+96*x^2) + (15*x-117*x^2+306*x^3)*Dx + (9*x^2-54*x^3)*Dx^2 - sage: L.generalized_series_solutions(3) - [x^(-1/3)*(1 + x + 8/3*x^2 + O(x^3)), x^(-1/3)*((1 + x + 8/3*x^2 + O(x^3))*log(x) + x - 59/12*x^2 + O(x^3))] - sage: list(map(L, _)) - [0, 0] - - sage: L = 216*(1+x+x^3) + x^3*(36-48*x^2+41*x^4)*Dx - x^7*(6+6*x-x^2+4*x^3)*Dx^2 - sage: L.generalized_series_solutions(3) - [exp(3*x^(-2))*x^(-2)*(1 + 91/12*x^2 + O(x^3)), exp(-2*x^(-3) + x^(-1))*x^2*(1 + 41/3*x + 2849/36*x^2 + O(x^3))] - sage: list(map(L, _)) - [0, 0] - - sage: L = 9 - 49*x - 2*x^2 + 6*x^2*(7 + 5*x)*Dx + 36*(-1 + x)*x^3*Dx^2 - sage: L.generalized_series_solutions() - [exp(x^(-1/2))*x^(4/3)*(1 + x^(2/2) + x^(4/2)), exp(-x^(-1/2))*x^(4/3)*(1 + x^(2/2) + x^(4/2))] - sage: L.generalized_series_solutions(ramification=False) - [] - - sage: L = 2*x^3*Dx^2 + 3*x^2*Dx-1 - sage: L.generalized_series_solutions() - [exp(a_0*x^(-1/2))] - sage: _[0].base_ring() - Number Field in a_0 with defining polynomial x^2 - 2 -``` - - -### `UnivariateDifferentialOperatorOverUnivariateRing.numerical_solution` (differential operators (D)) - -``` -Evaluate an analytic solution of this operator at a point of its Riemann -surface. - -INPUT: - -- ``ini`` (iterable) - initial values, in number equal to the order `r` - of the operator -- ``path`` - a path on the complex plane, specified as a list of - vertices `z_0, \dots, z_n` -- ``eps`` (floating-point number or ball, default 1e-16) - approximate - target accuracy -- ``post_transform`` (default: identity) - differential operator to be - applied to the solutions, see examples below -- see :class:`ore_algebra.analytic.context.Context` for advanced - options - -OUTPUT: - -A real or complex ball *enclosing* the value at `z_n` of the solution `y` -defined in the neighborhood of `z_0` by the initial values ``ini`` and -extended by analytic continuation along ``path``. - -When `z_0` is an ordinary point, the initial values are defined as the -first `r` coefficients of the power series expansion at `z_0` of the -desired solution `f`. In other words, ``ini`` must be equal to - -.. math:: [f(z_0), f'(z_0), f''(z_0)/2, \dots, f^{(r-1)}(z_0)/(r-1)!]. - -Generalized initial conditions at regular singular points are also -supported. If `z_0` is a regular point, the entries of ``ini`` are -interpreted as the coefficients of the monomials `(z-z_0)^n -\log(z-z_0)^k/k!` returned by :meth:`local_basis_monomials` in the -logarithmic series expansion of `f` at `z_0`. This definition reduces -to the previous one when `z_0` is an ordinary point. - -The accuracy parameter ``eps`` is used as an indication of the -*absolute* error the code should aim for. The diameter of the result -will typically be of the order of magnitude of ``eps``, but this is not -guaranteed to be the case. (It is a bug, however, if the returned ball -does not contain the exact result.) - -See :mod:`ore_algebra.analytic` for more information, and -:mod:`ore_algebra.examples` for additional examples. - -.. SEEALSO:: :meth:`numerical_transition_matrix` - -EXAMPLES: - -First a very simple example:: - - sage: from ore_algebra import DifferentialOperators - sage: Dops, x, Dx = DifferentialOperators() - sage: (Dx - 1).numerical_solution(ini=[1], path=[0, 1], eps=1e-50) - [2.7182818284590452353602874713526624977572470936999...] - -Evaluation points can be complex and can depend on symbolic constants:: - - sage: (Dx - 1).numerical_solution([1], [0, i + pi]) - [12.5029695888765...] + [19.4722214188416...]*I - -They can even be real or complex balls. In this case, the result -contains the image of the ball:: - - sage: (Dx - 1).numerical_solution([1], [0, CBF(1+i).add_error(0.01)]) - [1.5 +/- 0.0693] + [2.3 +/- 0.0506]*I - -Here, we use a more complicated analytic continuation path in order to -evaluate the branch of the complex arctangent function obtained by -turning around its singularity at `i` once:: - - sage: dop = (x^2 + 1)*Dx^2 + 2*x*Dx - sage: dop.numerical_solution([0, 1], [0, i+1, 2*i, i-1, 0]) - [3.14159265358979...] + [+/- ...]*I - -In some cases, this method is also able to compute limits of solutions -at regular singular points. This only works when all solutions of the -differential equation tend to finite values at the evaluation point:: - - sage: dop = (x - 1)^2*Dx^3 + Dx + 1 - sage: dop.local_basis_monomials(1) - [1, - (x - 1)^(1.500000000000000? - 0.866025403784439?*I), - (x - 1)^(1.500000000000000? + 0.866025403784439?*I)] - sage: dop.numerical_solution(ini=[1, 0, 0], path=[0, 1]) - [0.6898729110219401...] + [+/- ...]*I - - sage: dop = -(x+1)*(x-1)^3*Dx^2 + (x+3)*(x-1)^2*Dx - (x+3)*(x-1) - sage: dop.local_basis_monomials(1) - [x - 1, (x - 1)^2] - sage: dop.numerical_solution([1,0], [0,1]) - 0 - - sage: (Dx*x*Dx).numerical_solution(ini=[1,0],path=[1,0]) - Traceback (most recent call last): - ... - ValueError: solution may not have a finite limit at evaluation - point 0 (try using numerical_transition_matrix()) - -To obtain the values of the solution at several points in a single run, -enclose the corresponding points of the path in length-one lists. The -output then changes to a list of (point, solution value) pairs:: - - sage: (Dx - 1).numerical_solution([1], [[i/3] for i in range(4)]) - [(0, 1.00...), (1/3, [1.39...]), (2/3, [1.94...]), (1, [2.71...])] - - sage: (Dx - 1).numerical_solution([1], [0, [1]]) - [(1, [2.71828182845904...])] - -The ``post_transform`` parameter can be used to compute derivatives or -linear combinations of derivatives of the solution. Here, we use this -feature to evaluate the tenth derivative of the Airy `Ai` function:: - - sage: ini = [1/(3^(2/3)*gamma(2/3)), -1/(3^(1/3)*gamma(1/3))] - sage: (Dx^2-x).numerical_solution(ini, [0,2], post_transform=Dx^10) - [2.34553207877...] - sage: airy_ai(10, 2.) - 2.345532078777... - -A similar, slightly more complicated example:: - - sage: (Dx^2 - x).numerical_solution(ini, [0, 2], - ....: post_transform=1/x + x*Dx) - [-0.08871870365567...] - sage: t = SR.var('t') - sage: (airy_ai(t)/t + t*airy_ai_prime(t))(t=2.) - -0.08871870365567... - -Some no -... [truncated] -``` - - -### `UnivariateDifferentialOperatorOverUnivariateRing.numerical_transition_matrix` (differential operators (D)) - -``` -Compute a transition matrix along a path drawn in the complex plane. - -INPUT: - -- ``path`` - a path on the complex plane, specified as a list of - vertices `z_0, \dots, z_n` -- ``eps`` (floating-point number or ball) - target accuracy -- see :class:`ore_algebra.analytic.context.Context` for advanced - options - -OUTPUT: - -When ``self`` is an operator of order `r`, this method returns an `r×r` -matrix of real or complex balls. The returned matrix maps a vector of -“initial values at `z_0`” (i.e., the coefficients of the decomposition -of a solution in a certain canonical local basis at `z_0`) to “initial -values at `z_n`” that define the same solution, extended by analytic -continuation along the path ``path``. - -The “initial values” are the coefficients of the monomials returned by -:meth:`local_basis_monomials` in the local logarithmic power series -expansions of the solution at the corresponding point. When `z_i` is an -ordinary point, the corresponding vector of initial values is simply - -.. math:: [f(z_i), f'(z_i), f''(z_i)/2, \dots, f^{(r-1)}(z_i)/(r-1)!]. - -The accuracy parameter ``eps`` is used as an indication of the -*absolute* error that the code should aim for. The diameter of each -entry of the result will typically be of the order of magnitude of -``eps``, but this is not guaranteed to be the case. (It is a bug, -however, if the returned ball does not contain the exact result.) - -See :mod:`ore_algebra.analytic` for more information, and -:mod:`ore_algebra.examples` for additional examples. - -.. SEEALSO:: :meth:`numerical_solution` - -EXAMPLES: - -We can compute `\exp(1)` as the only entry of the transition matrix from -`0` to `1` for the differential equation `y' = y`:: - - sage: from ore_algebra import DifferentialOperators - sage: Dops, x, Dx = DifferentialOperators() - sage: (Dx - 1).numerical_transition_matrix([0, 1]) - [[2.7182818284590452 +/- 3.54e-17]] - -Now consider a second-order operator that annihilates `\arctan(x)` and the -constants. A basis of solutions is formed of the constant `1`, of the -form `1 + O(x^2)` as `x \to 0`, and the arctangent function, of the form -`x + O(x^2)`. Accordingly, the entries of the transition matrix from the -origin to `1 + i` are the values of these two functions and their first -derivatives:: - - sage: dop = (x^2 + 1)*Dx^2 + 2*x*Dx - sage: dop.numerical_transition_matrix([0, 1+i], 1e-10) - [ [1.00...] + [+/- ...]*I [1.017221967...] + [0.4023594781...]*I] - [ [+/- ...] + [+/- ...]*I [0.200000000...] + [-0.400000000...]*I] - -By making loops around singular points, we can compute local monodromy -matrices:: - - sage: dop.numerical_transition_matrix([0, i + 1, 2*i, i - 1, 0]) - [ [1.00...] + [+/- ...]*I [3.141592653589793...] + [+/-...]*I] - [ [+/- ...] + [+/- ...]*I [1.000000000000000...] + [+/-...]*I] - -Then we compute a connection matrix to the singularity itself:: - - sage: dop.numerical_transition_matrix([0, i], 1e-10) - [ ... [+/-...] + [-0.50000000...]*I] - [ ...1.000000... [0.7853981634...] + [0.346573590...]*I] - -Note that a path that crosses the branch cut of the complex logarithm -yields a different result:: - - sage: dop.numerical_transition_matrix([0, i - 1, i], 1e-10) - [ [+/-...] + [+/-...]*I [+/-...] + [-0.5000000000...]*I] - [ [1.00000...] + [+/-...]*I [-2.356194490...] + [0.3465735902...]*I] - -In general, if the operator has rational coefficients, its singular -points are algebraic numbers. In connection problems such as the above, -they need to be specified exactly. Here is a way to do it:: - - sage: dop = (x^2 - 2)*Dx^2 + x + 1 - sage: dop.numerical_transition_matrix([0, 1, QQbar(sqrt(2))], 1e-10) - [ [2.49388146...] + [+/-...]*I [2.40894178...] + [+/-...]*I] - [[-0.203541775...] + [6.68738570...]*I [0.204372067...] + [6.45961849...]*I] - -The operator itself may be defined over a number field (with a complex -embedding):: - - sage: K. = CyclotomicField(7) - sage: (Dx - zeta7).numerical_transition_matrix([0, 1]) - [[1.32375209616333...] + [1.31434281345999...]*I] - -Some notable examples of incorrect input:: - - sage: (Dx - 1).numerical_transition_matrix([]) - Traceback (most recent call last): - ... - ValueError: empty path - - sage: ((x - 1)*Dx + 1).numerical_transition_matrix([0, 2]) - Traceback (most recent call last): - ... - ValueError: Step 0 --> 2 passes through or too close to singular - point 1 (to compute the connection to a singular point, make it a - vertex of the path) - - sage: Dops.zero().numerical_transition_matrix([0, 1]) - Traceback (most recent call last): - ... - ValueError: operator must be nonzero -``` - - -### `UnivariateEulerDifferentialOperatorOverUnivariateRing.to_D` (differential operators (D)) - -``` -Return the differential operator corresponding to ``self`` - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_D()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - the standard derivation with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: A. = OreAlgebra(R, 'Tx') - sage: (Tx^4).to_D(OreAlgebra(R, 'Dx')) - x^4*Dx^4 + 6*x^3*Dx^3 + 7*x^2*Dx^2 + x*Dx - sage: (Tx^4).to_D('Dx').to_T(A) - Tx^4 -``` - - -### `UnivariateEulerDifferentialOperatorOverUnivariateRing.to_S` (differential operators (D)) - -``` -Return a recurrence operator annihilating the coefficient sequence of -every power series (at the origin) annihilated by ``self``. - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_S()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - the standard shift with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: A. = OreAlgebra(R, 'Tx') - sage: R2. = ZZ['n'] - sage: A2. = OreAlgebra(R2, 'Sn') - sage: (Tx - 1).to_S(A2) - n - 1 - sage: ((1+x)*Tx^2 + Tx).to_S(A2) - (n^2 + 3*n + 2)*Sn + n^2 - sage: ((x^3+x^2-x)*Tx + (x^2+1)).to_S(A2) - Sn^3 + (-n - 2)*Sn^2 + (n + 2)*Sn + n -``` - - -### `UnivariateRecurrenceOperatorOverUnivariateRing.to_D` (recurrence operators (S)) - -``` -Returns a differential operator which annihilates every power series whose -coefficient sequence is annihilated by ``self``. -The output operator may not be minimal. - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_D()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - the standard derivation with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: Rn. = ZZ['n']; Rx. = ZZ['x'] - sage: A. = OreAlgebra(Rn, 'Sn') - sage: B. = OreAlgebra(Rx, 'Dx') - sage: (Sn - 1).to_D(B) - (-x + 1)*Dx - 1 - sage: ((n+1)*Sn - 1).to_D(B) - x*Dx^2 + (-x + 1)*Dx - 1 - sage: (x*Dx-1).to_S(A).to_D(B) - x*Dx - 1 -``` - - -### `UnivariateRecurrenceOperatorOverUnivariateRing.to_T` (recurrence operators (S)) - -``` -Returns a differential operator, expressed in terms of the Euler derivation, -which annihilates every power series (about the origin) whose coefficient -sequence is annihilated by ``self``. -The output operator may not be minimal. - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_T()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - the Euler derivation with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: Rn. = ZZ['n']; Rx. = ZZ['x'] - sage: A. = OreAlgebra(Rn, 'Sn') - sage: B. = OreAlgebra(Rx, 'Tx') - sage: (Sn - 1).to_T(B) - (-x + 1)*Tx - x - sage: ((n+1)*Sn - 1).to_T(B) - Tx^2 - x*Tx - x - sage: (x*Tx-1).to_S(A).to_T(B) - x*Tx^2 + (x - 1)*Tx -``` - - -### `UnivariateRecurrenceOperatorOverUnivariateRing.to_list` (recurrence operators (S)) - -``` -Computes the terms of some sequence annihilated by ``self``. - -INPUT: - -- ``init`` -- a vector (or list or tuple) of initial values. - The components must be elements of ``self.base_ring().base_ring().fraction_field()``. - If the length is more than ``self.order()``, we do not check whether the given - terms are consistent with ``self``. -- ``n`` -- desired number of terms. -- ``start`` (optional) -- index of the sequence term which is represented - by the first entry of ``init``. Defaults to zero. -- ``append`` (optional) -- if ``True``, the computed terms are appended - to ``init`` list. Otherwise (default), a new list is created. -- ``padd`` (optional) -- if ``True``, the vector of initial values is implicitly - prolonged to the left (!) by zeros if it is too short. Otherwise (default), - the method raises a ``ValueError`` if ``init`` is too short. - -OUTPUT: - -A list of ``n`` terms whose `k` th component carries the sequence term with -index ``start+k``. -Terms whose calculation causes an error are represented by ``None``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R = ZZ['x']['n']; x = R('x'); n = R('n') - sage: A. = OreAlgebra(R, 'Sn') - sage: L = ((n+2)*Sn^2 - x*(2*n+3)*Sn + (n+1)) - sage: L.to_list([1, x], 5) - [1, x, (3*x^2 - 1)/2, (5*x^3 - 3*x)/2, (35*x^4 - 30*x^2 + 3)/8] - sage: polys = L.to_list([1], 5, padd=True) - sage: polys - [1, x, (3*x^2 - 1)/2, (5*x^3 - 3*x)/2, (35*x^4 - 30*x^2 + 3)/8] - sage: L.to_list([polys[3], polys[4]], 8, start=3) - [(5*x^3 - 3*x)/2, - (35*x^4 - 30*x^2 + 3)/8, - (63*x^5 - 70*x^3 + 15*x)/8, - (231*x^6 - 315*x^4 + 105*x^2 - 5)/16, - (429*x^7 - 693*x^5 + 315*x^3 - 35*x)/16, - (6435*x^8 - 12012*x^6 + 6930*x^4 - 1260*x^2 + 35)/128, - (12155*x^9 - 25740*x^7 + 18018*x^5 - 4620*x^3 + 315*x)/128, - (46189*x^10 - 109395*x^8 + 90090*x^6 - 30030*x^4 + 3465*x^2 - 63)/256] - sage: ((n-5)*Sn - 1).to_list([1], 10) - [1, 1/-5, 1/20, 1/-60, 1/120, -1/120, None, None, None, None] -``` - - -### `UnivariateRecurrenceOperatorOverUnivariateRing.forward_matrix_bsplit` (recurrence operators (S)) - -``` -Uses division-free binary splitting to compute a product of ``n`` -consecutive companion matrices of ``self``. - -If ``self`` annihilates some sequence `c` of order `r`, this -allows rapidly computing `c_n, \ldots, c_{n+r-1}` (or just `c_n`) -without generating all the intermediate values. - -INPUT: - -- ``n`` -- desired number of terms to move forward -- ``start`` (optional) -- starting index. Defaults to zero. - -OUTPUT: - -A pair `(M, Q)` where `M` is an `r` by `r` matrix and `Q` -is a scalar, such that `M / Q` is the product of the companion -matrix at `n` consecutive indices. - -We have `Q [c_{s+n}, \ldots, c_{s+r-1+n}]^T = M [c_s, c_{s+1}, \ldots, c_{s+r-1}]^T`, -where `s` is the initial position given by ``start``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R = ZZ - sage: Rx. = R[] - sage: Rxk. = Rx[] - sage: Rxks = OreAlgebra(Rxk, 'Sk') - sage: ann = Rxks([1+k, -3*x - 2*k*x, 2+k]) - sage: initial = Matrix([[1], [x]]) - sage: M, Q = ann.forward_matrix_bsplit(5) - sage: (M * initial).change_ring(QQ['x']) / Q - [ 63/8*x^5 - 35/4*x^3 + 15/8*x] - [231/16*x^6 - 315/16*x^4 + 105/16*x^2 - 5/16] - - sage: Matrix([[legendre_P(5, x)], [legendre_P(6, x)]]) - [ 63/8*x^5 - 35/4*x^3 + 15/8*x] - [231/16*x^6 - 315/16*x^4 + 105/16*x^2 - 5/16] - - - sage: Sk = Rxks.gen() - sage: (Sk^2 - 1).forward_matrix_param_rectangular(1, 10) - ( - [1 0] - [0 1], 1 - ) - -TODO: this should detect if the base coefficient ring is QQ (etc.) -and then switch to ZZ (etc.) internally. -``` - - -### `UnivariateRecurrenceOperatorOverUnivariateRing.annihilator_of_sum` (recurrence operators (S)) - -``` -Returns an operator `L` which annihilates all the indefinite sums `\sum_{k=0}^n a_k` -where `a_n` runs through the sequences annihilated by ``self``. -The output operator is not necessarily of smallest possible order. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: A. = OreAlgebra(R, 'Sx') - sage: ((x+1)*Sx - x).annihilator_of_sum() # constructs L such that L(H_n) == 0 - (x + 2)*Sx^2 + (-2*x - 3)*Sx + x + 1 -``` - - -### `UnivariateRecurrenceOperatorOverUnivariateRing.annihilator_of_composition` (recurrence operators (S)) - -``` -Returns an operator `L` which annihilates all the sequences `f(floor(a(n)))` -where `f` runs through the functions annihilated by ``self``. -The output operator is not necessarily of smallest possible order. - -INPUT: - -- ``a`` -- a polynomial `u*x+v` where `x` is the generator of the base ring, - `u` and `v` are integers or rational numbers. If they are rational, - the base ring of the parent of ``self`` must contain ``QQ``. -- ``solver`` (optional) -- a callable object which applied to a matrix - with polynomial entries returns its kernel. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = QQ['x'] - sage: A. = OreAlgebra(R, 'Sx') - sage: ((2+x)*Sx^2-(2*x+3)*Sx+(x+1)).annihilator_of_composition(2*x+5) - (16*x^3 + 188*x^2 + 730*x + 936)*Sx^2 + (-32*x^3 - 360*x^2 - 1340*x - 1650)*Sx + 16*x^3 + 172*x^2 + 610*x + 714 - sage: ((2+x)*Sx^2-(2*x+3)*Sx+(x+1)).annihilator_of_composition(1/2*x) - (x^2 + 11*x + 30)*Sx^6 + (-3*x^2 - 25*x - 54)*Sx^4 + (3*x^2 + 17*x + 26)*Sx^2 - x^2 - 3*x - 2 - sage: ((2+x)*Sx^2-(2*x+3)*Sx+(x+1)).annihilator_of_composition(100-x) - (-x + 99)*Sx^2 + (2*x - 199)*Sx - x + 100 -``` - - -### `UnivariateRecurrenceOperatorOverUnivariateRing.annihilator_of_interlacing` (recurrence operators (S)) - -``` -Returns an operator `L` which annihilates any sequence which can be -obtained by interlacing sequences annihilated by ``self`` and the -operators given in the arguments. - -More precisely, if ``self`` and the operators given in the arguments are -denoted `L_1,L_2,\dots,L_m`, and if `f_1(n),\dots,f_m(n)` are some -sequences such that `L_i` annihilates `f_i(n)`, then the output operator -`L` annihilates sequence -`f_1(0),f_2(0),\dots,f_m(0),f_1(1),f_2(1),\dots,f_m(1),\dots`, the -interlacing sequence of `f_1(n),\dots,f_m(n)`. - -The output operator is not necessarily of smallest possible order. - -The ``other`` operators must be coercible to the parent of ``self``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = QQ['x'] - sage: A. = OreAlgebra(R, 'Sx') - sage: (x*Sx - (x+1)).annihilator_of_interlacing(Sx - (x+1), Sx + 1) - (x^3 + 17/2*x^2 + 5/2*x - 87/2)*Sx^9 + (-1/3*x^4 - 11/2*x^3 - 53/2*x^2 - 241/6*x + 14)*Sx^6 + (7/2*x^2 + 67/2*x + 205/2)*Sx^3 + 1/3*x^4 + 13/2*x^3 + 77/2*x^2 + 457/6*x + 45 -``` - - -### `UnivariateRecurrenceOperatorOverUnivariateRing.generalized_series_solutions` (recurrence operators (S)) - -``` -Returns the generalized series solutions of this operator. - -These are solutions of the form - - `(x/e)^{x u/v}\rho^x\exp\bigl(c_1 x^{1/m} +...+ c_{v-1} x^{1-1/m}\bigr)x^\alpha p(x^{-1/m},\log(x))` - -where - -* `e` is Euler's constant (2.71...) -* `v` is a positive integer -* `u` is an integer; the term `(x/e)^(v/u)` is called the "superexponential part" of the solution -* `\rho` is an element of an algebraic extension of the coefficient field `K` - (the algebra's base ring's base ring); the term `\rho^x` is called the "exponential part" of - the solution -* `c_1,...,c_{v-1}` are elements of `K(\rho)`; the term `\exp(...)` is called the "subexponential - part" of the solution -* `m` is a positive integer multiple of `v`, it is called the object's "ramification" -* `\alpha` is an element of some algebraic extension of `K(\rho)`; the term `n^\alpha` is called - the "polynomial part" of the solution (even if `\alpha` is not an integer) -* `p` is an element of `K(\rho)(\alpha)[[x]][y]`. It is called the "expansion part" of the solution. - -An operator of order `r` has exactly `r` linearly independent solutions of this form. -This method computes them all, unless the flags specified in the arguments rule out -some of them. - -Generalized series solutions are asymptotic expansions of sequences annihilated by the operator. - -At present, the method only works for operators where `K` is some field which supports -coercion to ``QQbar``. - -INPUT: - -- ``n`` (default: 5) -- minimum number of terms in the expansions parts to be computed. -- ``dominant_only`` (default: False) -- if set to True, only compute solution(s) with maximal - growth. -- ``real_only`` (default: False) -- if set to True, only compute solution(s) where `\rho,c_1,...,c_{v-1},\alpha` - are real. -- ``infolevel`` (default: 0) -- if set to a positive integer, the methods prints some messages - about the progress of the computation. - -OUTPUT: - -- a list of ``DiscreteGeneralizedSeries`` objects forming a fundamental system for this operator. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = QQ['n']; A. = OreAlgebra(R, 'Sn') - sage: (Sn - (n+1)).generalized_series_solutions() - [(n/e)^n*n^(1/2)*(1 + 1/12*n^(-1) + 1/288*n^(-2) - 139/51840*n^(-3) - 571/2488320*n^(-4) + O(n^(-5)))] - sage: list(map(Sn - (n+1), _)) - [0] - - sage: L = ((n+1)*Sn - n).annihilator_of_sum().symmetric_power(2) - sage: L.generalized_series_solutions() - [1 + O(n^(-5)), - (1 + O(n^(-5)))*log(n) + 1/2*n^(-1) - 1/12*n^(-2) + 1/120*n^(-4) + O(n^(-5)), - (1 + O(n^(-5)))*log(n)^2 + (n^(-1) - 1/6*n^(-2) + 1/60*n^(-4) + O(n^(-5)))*log(n) + 1/4*n^(-2) - 1/12*n^(-3) + 1/144*n^(-4) + O(n^(-5))] - sage: list(map(L, _)) - [0, 0, 0] - - sage: L = n^2*(1-2*Sn+Sn^2) + (n+1)*(1+Sn+Sn^2) - sage: L.generalized_series_solutions() # long time (1.4 s) - [exp(3.464101615137755?*I*n^(1/2))*n^(1/4)*(1 - 2.056810333988042?*I*n^(-1/2) - 1107/512*n^(-2/2) + (0.?e-19 + 1.489453749877895?*I)*n^(-3/2) + 2960239/2621440*n^(-4/2) + (0.?e-19 - 0.926161373412572?*I)*n^(-5/2) - 16615014713/46976204800*n^(-6/2) + (0.?e-20 + 0.03266142931818572?*I)*n^(-7/2) + 16652086533741/96207267430400*n^(-8/2) + (0.?e-20 - 0.1615093987591473?*I)*n^(-9/2) + O(n^(-10/2))), exp(-3.464101615137755?*I*n^(1/2))*n^(1/4)*(1 + 2.056810333988042?*I*n^(-1/2) - 1107/512*n^(-2/2) + (0.?e-19 - 1.489453749877895?*I)*n^(-3/2) + 2960239/2621440*n^(-4/2) + (0.?e-19 + 0.926161373412572?*I)*n^(-5/2) - 16615014713/46976204800*n^(-6/2) + (0.?e-20 - 0.03266142931818572?*I)*n^(-7/2) + 16652086533741/96207267430400*n^(-8/2) + (0.?e-20 + 0.1615093987591473?*I)*n^(-9/2) + O(n^(-10/2)))] - - sage: L = guess([(-3)^k*(k+1)/(2*k+4) - 2^k*k^3/(k+3) for k in range(500)], A) - sage: L.generalized_series_solutions() - [2^n*n^2*(1 - 3*n^(-1) + 9*n^(-2) - 27*n^(-3) + 81*n^(-4) + O(n^(-5))), (-3)^n*(1 - n^(-1) + 2*n^(-2) - 4*n^(-3) + 8*n^(-4) + O(n^(-5)))] - sage: L.generalized_series_solutions(dominant_only=True) - [(-3)^n*(1 - n^(-1) + 2*n^(-2) - 4*n^(-3) + 8*n^(-4) + O(n^(-5)))] - -TESTS:: - - sage: rop = (-8 -12*Sn + (n^2+5*n+6)*Sn^3) - sage: rop - (n^2 + 5*n + 6)*Sn^3 - 12*Sn - 8 - sage: rop.generalized_series_solutions(1) # long time (7 s) - [(n/e)^(-2/3*n)*2^n*exp(3*n^(1/3))*n^(-2/3)*(1 + 3/2*n^(-1/3) + 9/8*n^(-2/3) + O(n^(-3/3))), - (n/e)^(-2/3*n)*(-1.000000000000000? + 1.732050807568878?*I)^n*exp((-1.500000000000000? + 2.598076211353316?*I)*n^(1/3))*n^(-2/3)*(1 + (-0.750000000000000? - 1.299038105676658?*I)*n^(-1/3) + (-0.562500000000000? + 0.974278579257494?*I)*n^(-2/3) + O(n^(-3/3))), - (n/e)^(-2/3*n)*(-1.000000000000000? - 1.732050807568878?*I)^n*exp((-1.500000000000000? - 2.598076211353316?*I)*n^(1/3))*n^(-2/3)*(1 + (-0.750000000000000? + 1.299038105676658?*I)*n^(-1/3) + (-0.562500000000000? - 0.974278579257494?*I)*n^(-2/3) + O(n^(-3/3)))] -``` - - -### `UnivariateDifferenceOperatorOverUnivariateRing.to_S` (recurrence operators (S)) - -``` -Returns the differential operator corresponding to ``self`` - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_S()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - a standard shift with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: R. = ZZ['x'] - sage: A. = OreAlgebra(R, 'Fx') - sage: (Fx^4).to_S(OreAlgebra(R, 'Sx')) - Sx^4 - 4*Sx^3 + 6*Sx^2 - 4*Sx + 1 - sage: (Fx^4).to_S('Sx') - Sx^4 - 4*Sx^3 + 6*Sx^2 - 4*Sx + 1 -``` - - -### `UnivariateDifferenceOperatorOverUnivariateRing.to_D` (recurrence operators (S)) - -``` -Returns a differential operator which annihilates every power series (about -the origin) whose coefficient sequence is annihilated by ``self``. -The output operator may not be minimal. - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_D()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - the standard derivation with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: Rn. = ZZ['n']; Rx. = ZZ['x'] - sage: A. = OreAlgebra(Rn, 'Fn') - sage: B. = OreAlgebra(Rx, 'Dx') - sage: Fn.to_D(B) - (-x + 1)*Dx - 1 - sage: ((n+1)*Fn - 1).to_D(B) - (-x^2 + x)*Dx^2 + (-4*x + 1)*Dx - 2 - sage: (x*Dx-1).to_F(A).to_D(B) - x*Dx - 1 -``` - - -### `UnivariateDifferenceOperatorOverUnivariateRing.to_T` (recurrence operators (S)) - -``` -Returns a differential operator, expressed in terms of the Euler derivation, -which annihilates every power series (about the origin) whose coefficient -sequence is annihilated by ``self``. -The output operator may not be minimal. - -INPUT: - -- ``alg`` -- the Ore algebra in which the output should be expressed. - The algebra must satisfy ``alg.base_ring().base_ring() == self.base_ring().base_ring()`` - and ``alg.is_T()`` is not ``False``. - Instead of an algebra object, also a string can be passed as argument. - This amounts to specifying an Ore algebra over ``self.base_ring()`` with - the Euler derivation with respect to ``self.base_ring().gen()``. - -EXAMPLES:: - - sage: from ore_algebra import * - sage: Rn. = ZZ['n']; Rx. = ZZ['x'] - sage: A. = OreAlgebra(Rn, 'Fn') - sage: B. = OreAlgebra(Rx, 'Tx') - sage: Fn.to_T(B) - (-x + 1)*Tx - x - sage: ((n+1)*Fn - 1).to_T(B) - (-x + 1)*Tx^2 - 3*x*Tx - 2*x - sage: (x*Tx-1).to_F(A).to_T(B) - x*Tx^2 + (x - 1)*Tx -``` diff --git a/apn/lean/loogle-build.sh b/apn/lean/loogle-build.sh new file mode 100644 index 00000000..a222728c --- /dev/null +++ b/apn/lean/loogle-build.sh @@ -0,0 +1,57 @@ +#!/bin/bash +# Build the Loogle search CLI against the FC project's exact Mathlib +# (Dockerfile stage loogle_build; usage: loogle-build.sh ). +# +# Loogle is built as its own Lake project at /opt/loogle, retargeted to the +# FC project: the project's lean-toolchain verbatim, and loogle's mathlib +# requirement moved from "master" to the rev the project's manifest pins. +# Deleting loogle's own lake-manifest.json makes `lake update` re-resolve all +# transitive deps from that pinned mathlib's manifest -- i.e. to exactly the +# revs the FC project uses. (Do NOT add loogle to the FC project itself: +# `lake update loogle` there pulls transitive deps from loogle's stale +# manifest and drifts the project off its pins.) +# +# Instead of cloning a second multi-GB Mathlib, loogle's .lake/packages is a +# symlink to the FC project's packages -- same revs by construction, already +# built. The binary embeds its olean search path at compile time (all under +# /opt/loogle/.lake/... plus the toolchain), and its index lookup finds +# LoogleMathlibCache.extra next to that module's olean, so at runtime the +# plain binary works with no flags and no wrapper; the agent stage copies the +# binary, /opt/loogle/.lake/build/lib, and recreates the packages symlink. +set -euo pipefail + +loogle_commit="$1" +project=/workspace/leanproject + +mathlib_rev="$(python3 -c " +import json +packages = json.load(open('$project/lake-manifest.json'))['packages'] +print(next(p['rev'] for p in packages if p['name'] == 'mathlib')) +")" + +git clone https://github.com/nomeata/loogle.git /opt/loogle +cd /opt/loogle +git checkout --detach "${loogle_commit}" + +cp "$project/lean-toolchain" lean-toolchain +sed -i "s|@ \"master\"|@ \"${mathlib_rev}\"|" lakefile.lean +grep -q "${mathlib_rev}" lakefile.lean # the sed matched +rm lake-manifest.json +mkdir .lake +ln -s "$project/.lake/packages" .lake/packages + +lake update +lake build loogle LoogleMathlibCache + +# Persist the search index where Find.cachePath looks for it (next to +# LoogleMathlibCache.olean), then prove the flag-less invocation the agent +# will use. Index construction peaks ~10 GB RSS. +bin=.lake/build/bin/loogle +"$bin" --write-index .lake/build/lib/lean/LoogleMathlibCache.extra --json "Nat.Prime" > /tmp/smoke.json +grep -q '"name"' /tmp/smoke.json +"$bin" --json "Nat.Prime" > /tmp/smoke.json +grep -q '"name"' /tmp/smoke.json +rm /tmp/smoke.json + +# Only the oleans and the index pickle matter at runtime. +find .lake/build/lib -type f ! -name '*.olean' ! -name '*.extra' -delete diff --git a/apn/lean/loogle.sh b/apn/lean/loogle.sh deleted file mode 100644 index 4840df30..00000000 --- a/apn/lean/loogle.sh +++ /dev/null @@ -1,19 +0,0 @@ -#!/bin/bash -# Wrapper for the Loogle CLI (built in the Dockerfile's loogle_build stage). -# Loogle ignores LEAN_PATH -- its --path flags REPLACE the compiled-in search -# path entirely -- so every olean root is listed explicitly: the FC project's -# packages (Mathlib and its deps; the same rev loogle was built against), the -# project's own build, loogle's modules, and the toolchain's stdlib (derived -# from the project's lean-toolchain: "leanprover/lean4:vX" installs under -# "leanprover--lean4---vX"). The prebuilt index skips index construction, not -# the ~30s Mathlib import -- batch queries via `loogle -i` reading stdin. -set -euo pipefail -ARGS=() -for p in /workspace/leanproject/.lake/packages/*/.lake/build/lib/lean; do - ARGS+=(--path "$p") -done -ARGS+=(--path /workspace/leanproject/.lake/build/lib/lean) -ARGS+=(--path /opt/loogle/lib/lean) -tc_dir="$(sed 's|/|--|g; s|:|---|g' /workspace/leanproject/lean-toolchain)" -ARGS+=(--path "/root/.elan/toolchains/${tc_dir}/lib/lean") -exec /opt/loogle/bin/loogle "${ARGS[@]}" --read-index /opt/loogle/loogle.index "$@" diff --git a/apn/prompts.py b/apn/prompts.py index f1147927..4ad09cd5 100644 --- a/apn/prompts.py +++ b/apn/prompts.py @@ -50,7 +50,7 @@ def user_prompt(path: str, token_limit: int | None, literature: bool, util_modul Your environment has the following available: * A Lean 4 toolchain with Mathlib, plus the `loogle` search CLI. * The `sage` computer algebra system (version 10), with `gp` (PARI), `gap`, `Singular`, and `maxima` also on PATH. -* `python3` with numpy, scipy, sympy, mpmath, pandas, networkx, igraph, python-flint, highspy (LP/MIP), python bindings for the solvers below (z3, cvc5, OR-Tools CP-SAT, pysat), snappy (SnapPy, 3-manifolds), and ore_algebra (D-finite sequences, used from sage). +* `python3` with numpy, scipy, sympy, mpmath, pandas, networkx, igraph, python-flint, highspy (LP/MIP), python bindings for the solvers below (z3, cvc5, OR-Tools CP-SAT, pysat), and snappy (SnapPy, 3-manifolds). * Solver binaries: `z3`, `cvc5`, `kissat` (SAT, DIMACS), `cryptominisat` (SAT), `csdp` (semidefinite programs), `msolve` (polynomial systems), `prover9`/`mace4` (first-order prover / countermodel finder). * Mathematical CLI tools: `primesieve`, `primecount`, `ecm` (integer factorization), nauty's generators (`geng`, `genbg`, ...), `plantri` (planar graphs), `polymake` (polyhedral geometry), `normaliz` (rational cones), 4ti2 (lattice ideals), `lrs` (vertex enumeration), `M2` (Macaulay2, commutative algebra), `regina-python` (low-dimensional topology). * `git`, `rg`, and `jq` diff --git a/tests/test_agent_image.py b/tests/test_agent_image.py index 151c9064..902f0a70 100644 --- a/tests/test_agent_image.py +++ b/tests/test_agent_image.py @@ -100,10 +100,6 @@ "ortools", "pysat", # python-sat "snappy", # SnapPy - # ore_algebra is a sage library: importing it before sage.all trips sage's - # circular-import guard, so the contract (and the agent's usage) is - # "import sage.all first". - "sage.all, ore_algebra", "sage.all", ] @@ -121,7 +117,6 @@ "prover9", "regina", "snappy", - "ore_algebra", "python-flint", ] From f145fa14f1f7fcbee344917d0e34b41faa00933e Mon Sep 17 00:00:00 2001 From: tadamcz Date: Sat, 29 Aug 2026 00:11:58 +0100 Subject: [PATCH 4/7] Adopt upstream Loogle's 'Running locally' contract Loogle master (pinned at 9f11169) is dependency-free, honors lake env's LEAN_PATH, and caches its search index next to the searched module's .olean with automatic invalidation -- and it builds cleanly under this track's v4.27.0 toolchain. So the loogle_build stage is now exactly upstream's documented recipe (clone, copy the project's lean-toolchain, lake build) plus one query to bake the Mathlib index; the agent image copies the binary and that index file. Agents invoke it per the vendored doc: lake env loogle --module Mathlib '' (~15s per query with the baked index). The rev-retargeting build script, packages symlink, and Mathlib-rev coupling are all gone -- only the toolchain ties loogle to the pin. Verified: full contract suite green against the rebuilt image. --- apn/lean/Dockerfile | 46 +++++++++++++++------------ apn/lean/docs/loogle/loogle.md | 29 ++++++++++++----- apn/lean/loogle-build.sh | 57 ---------------------------------- tests/test_agent_image.py | 9 ++++-- 4 files changed, 54 insertions(+), 87 deletions(-) delete mode 100644 apn/lean/loogle-build.sh diff --git a/apn/lean/Dockerfile b/apn/lean/Dockerfile index be1bf9c5..92b64eb4 100644 --- a/apn/lean/Dockerfile +++ b/apn/lean/Dockerfile @@ -50,7 +50,8 @@ # toolchain (plan §2.1). # # On an FC-pin bump: the exporter's and Loogle's builds move with it (Loogle -# is rebuilt against the new pin's Mathlib rev; see `loogle_build`). +# is dependency-free and merely rebuilt at the pin's toolchain, with its +# Mathlib search index rebaked; see `loogle_build`). # On a comparator bump: move LEAN4EXPORT_COMMIT to the rev in comparator's # lake-manifest.json, re-verify the toolchain-override build, and re-run the # primitive-constants check (plan §2.3; the gold-proof suite exercises it). @@ -345,21 +346,24 @@ RUN arch="$(uname -m)" \ && rm -rf /tmp/cvc5 /tmp/cvc5.zip # --------------------------------------------------------------------------- # -# loogle_build: the Loogle type-pattern Mathlib search CLI, the one pin-tied # -# addition to the agent's compute stack. Built FROM base at /opt/loogle, # -# retargeted to the project's toolchain + pinned Mathlib rev and sharing the # -# project's package checkouts via symlink (loogle-build.sh) -- so the binary # -# compiles against the very oleans the agent image carries, its embedded # -# search path resolves at runtime, and its search index sits where it # -# auto-finds it. The agent stage copies the raw binary plus loogle's build # -# lib and recreates the symlink: no second Mathlib, no wrapper, no flags. # -# The Loogle rev is chosen inside the pin's toolchain window. # +# loogle_build: the Loogle type-pattern Mathlib search CLI. Upstream's # +# "Running locally" contract: the binary is dependency-free, must merely be # +# built with the TARGET project's toolchain, and then searches any Lake # +# project via `lake env loogle --module ""` (it reads LEAN_PATH). # +# The first query builds a search index cached next to the module's .olean # +# and auto-invalidated when the oleans change; running one here bakes that # +# index (and smoke-tests the build), so agents get fast queries. # # --------------------------------------------------------------------------- # FROM base AS loogle_build -ARG LOOGLE_COMMIT=79343e3e37b64046e6b555936682012e80300df1 -COPY loogle-build.sh /tmp/loogle-build.sh -RUN bash /tmp/loogle-build.sh "${LOOGLE_COMMIT}" +ARG LOOGLE_COMMIT=9f11169aaebf1ed1e7dcc4077f2aafe0fcf66fd0 +RUN git clone https://github.com/nomeata/loogle.git /opt/loogle \ + && git -C /opt/loogle checkout --detach "${LOOGLE_COMMIT}" \ + && cp /workspace/leanproject/lean-toolchain /opt/loogle/lean-toolchain \ + && cd /opt/loogle \ + && lake build \ + && cd /workspace/leanproject \ + && lake env /opt/loogle/.lake/build/bin/loogle --module Mathlib "Nat.Prime" > /dev/null # --------------------------------------------------------------------------- # # agent: the agent's workspace. Layer order is big/stable first (the conda # @@ -390,14 +394,16 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # Source-built solvers (kissat, plantri, prover9/mace4, msolve, cvc5). COPY --from=solvers_build /out/bin/ /usr/local/bin/ -# Loogle: the raw binary, its module oleans + search index at the paths the -# binary's compile-time-embedded search path expects, and the packages -# symlink through which that embedded path reaches the project's own Mathlib -# oleans (same revs as the build, by construction -- see loogle-build.sh). -# No wrapper, no flags: `loogle "..."` just works. +# Loogle: the dependency-free binary, plus the Mathlib search index it baked +# next to Mathlib.olean (COPY preserves mtimes, and this stage shares base's +# layers with loogle_build, so the index stays valid; were it ever judged +# stale, loogle transparently rebuilds it). Invocation, per upstream's docs +# (vendored at /opt/docs/loogle): from the project, +# lake env loogle --module Mathlib "" COPY --from=loogle_build /opt/loogle/.lake/build/bin/loogle /usr/local/bin/loogle -COPY --from=loogle_build /opt/loogle/.lake/build/lib /opt/loogle/.lake/build/lib -RUN ln -s /workspace/leanproject/.lake/packages /opt/loogle/.lake/packages +COPY --from=loogle_build \ + /workspace/leanproject/.lake/packages/mathlib/.lake/build/lib/lean/Mathlib.loogle-index \ + /workspace/leanproject/.lake/packages/mathlib/.lake/build/lib/lean/Mathlib.loogle-index # In-sandbox references (the sandbox has no network): vendored, version-matched # docs for the tools whose syntax the agent is unlikely to know cold. Last: diff --git a/apn/lean/docs/loogle/loogle.md b/apn/lean/docs/loogle/loogle.md index 75ff717a..8af84e9f 100644 --- a/apn/lean/docs/loogle/loogle.md +++ b/apn/lean/docs/loogle/loogle.md @@ -1,4 +1,4 @@ - + # Loogle Loogle searches Lean and Mathlib definitions and theorems. @@ -46,7 +46,10 @@ hypothesis of the form `_ < _` (if there were any such lemmas). Metavariables (` ## CLI usage - $ loogle '(List.replicate (_ + _) _ = _)' +The loogle binary searches any Lake project of the same Lean toolchain. Run it +from the project via `lake env` (which supplies the olean search path): + + $ lake env loogle --module Mathlib '(List.replicate (_ + _) _ = _)' Found 5 declarations mentioning List.replicate, HAdd.hAdd and Eq. Of these, 3 match your patterns. @@ -54,6 +57,11 @@ hypothesis of the form `_ < _` (if there were any such lemmas). Metavariables (` List.replicate_succ List.replicate_succ' +The first call builds the search index (slow); by default loogle caches it on +disk next to the module's `.olean` so subsequent calls are fast, and quietly +rebuilds it whenever the underlying `.olean`s change. (In this image the +Mathlib index is prebuilt, so queries are fast from the start.) + USAGE: loogle [OPTIONS] [QUERY] @@ -63,9 +71,14 @@ hypothesis of the form `_ < _` (if there were any such lemmas). Metavariables (` --json, -j print result in JSON format --module mod import this module (default: Mathlib) --path path search for .olean files here (default: the build time path) - --write-index file persists the search index to a file - --read-index file read the search index from a file. This file is blindly trusted! - -By default, it will create an internal index upon starting, which takes a bit. -You can use `--write-index` and `--read-index` to cache that, but it is your -responsibility to pass the right index for the given module and search path. + --index-mode MODE how to manage the on-disk search index. One of: + use (default) load if present and up-to-date, + otherwise build and write + read load existing index; refuse to start if it + is missing or out of date + write always (re)build the index and write it + none build in memory and discard on exit + --index-file PATH override the default index path. The default lives + next to the root module's .olean (with .loogle-index + extension); pass this if that location is read-only. + --max-results n limit the number of returned hits (default: 200) diff --git a/apn/lean/loogle-build.sh b/apn/lean/loogle-build.sh deleted file mode 100644 index a222728c..00000000 --- a/apn/lean/loogle-build.sh +++ /dev/null @@ -1,57 +0,0 @@ -#!/bin/bash -# Build the Loogle search CLI against the FC project's exact Mathlib -# (Dockerfile stage loogle_build; usage: loogle-build.sh ). -# -# Loogle is built as its own Lake project at /opt/loogle, retargeted to the -# FC project: the project's lean-toolchain verbatim, and loogle's mathlib -# requirement moved from "master" to the rev the project's manifest pins. -# Deleting loogle's own lake-manifest.json makes `lake update` re-resolve all -# transitive deps from that pinned mathlib's manifest -- i.e. to exactly the -# revs the FC project uses. (Do NOT add loogle to the FC project itself: -# `lake update loogle` there pulls transitive deps from loogle's stale -# manifest and drifts the project off its pins.) -# -# Instead of cloning a second multi-GB Mathlib, loogle's .lake/packages is a -# symlink to the FC project's packages -- same revs by construction, already -# built. The binary embeds its olean search path at compile time (all under -# /opt/loogle/.lake/... plus the toolchain), and its index lookup finds -# LoogleMathlibCache.extra next to that module's olean, so at runtime the -# plain binary works with no flags and no wrapper; the agent stage copies the -# binary, /opt/loogle/.lake/build/lib, and recreates the packages symlink. -set -euo pipefail - -loogle_commit="$1" -project=/workspace/leanproject - -mathlib_rev="$(python3 -c " -import json -packages = json.load(open('$project/lake-manifest.json'))['packages'] -print(next(p['rev'] for p in packages if p['name'] == 'mathlib')) -")" - -git clone https://github.com/nomeata/loogle.git /opt/loogle -cd /opt/loogle -git checkout --detach "${loogle_commit}" - -cp "$project/lean-toolchain" lean-toolchain -sed -i "s|@ \"master\"|@ \"${mathlib_rev}\"|" lakefile.lean -grep -q "${mathlib_rev}" lakefile.lean # the sed matched -rm lake-manifest.json -mkdir .lake -ln -s "$project/.lake/packages" .lake/packages - -lake update -lake build loogle LoogleMathlibCache - -# Persist the search index where Find.cachePath looks for it (next to -# LoogleMathlibCache.olean), then prove the flag-less invocation the agent -# will use. Index construction peaks ~10 GB RSS. -bin=.lake/build/bin/loogle -"$bin" --write-index .lake/build/lib/lean/LoogleMathlibCache.extra --json "Nat.Prime" > /tmp/smoke.json -grep -q '"name"' /tmp/smoke.json -"$bin" --json "Nat.Prime" > /tmp/smoke.json -grep -q '"name"' /tmp/smoke.json -rm /tmp/smoke.json - -# Only the oleans and the index pickle matter at runtime. -find .lake/build/lib -type f ! -name '*.olean' ! -name '*.extra' -delete diff --git a/tests/test_agent_image.py b/tests/test_agent_image.py index 902f0a70..e956a9ac 100644 --- a/tests/test_agent_image.py +++ b/tests/test_agent_image.py @@ -234,9 +234,14 @@ async def test_cpsat_solves_trivial_model(agent_env: SandboxEnvironment) -> None @pytest.mark.asyncio(loop_scope="module") async def test_loogle_finds_nat_prime(agent_env: SandboxEnvironment) -> None: - # Cold start loads the prebuilt index + Mathlib oleans; generous timeout. + # Upstream's documented invocation (vendored at /opt/docs/loogle): from + # the project, via `lake env`. The Mathlib index is prebuilt in the image, + # so this must not fall into the slow index-construction path -- but cold + # start still imports Mathlib, hence the generous timeout. code, stdout, stderr = await _bash( - agent_env, "loogle 'Nat.Prime'", timeout=900 + agent_env, + "cd /workspace/leanproject && lake env loogle --module Mathlib 'Nat.Prime'", + timeout=900, ) assert code == 0, f"loogle failed:\n{stderr[-2000:]}" assert "Nat.Prime" in stdout From 1f32c03ff5fa48d192dd1c59f99811050001af60 Mon Sep 17 00:00:00 2001 From: tadamcz Date: Sat, 29 Aug 2026 02:01:56 +0100 Subject: [PATCH 5/7] Expand the agent tool roster; download docs at build from pinned sources The corpus-sweep delta on the compute-stack rework. Every addition was route-verified empirically (conda/apt probes on both arches, sha256'd release binaries, trial source builds on arm64) before landing: - conda: clingo, cvxpy, clarabel. SCIP arrives via pyscipopt's bundled wheel instead (no scip/soplex build coexists with the sage stack's boost pin; exact rational LP stays covered by glpk's --exact). - pip: pyscipopt, graphillion (sdist, verified on py3.13), pysindy, hypothesis, libsemigroups_pybind11, pymanopt. - apt: topcom, cadabra2, minizinc, berkeley-abc, eprover, mpsolve, default-jre-headless. - solvers_build: vampire (pinned release, both arches), drat-trim + lrat-check, cake_lpr (upstream's pre-generated per-arch asm), breakid, smsg (SAT modulo symmetries), march_cu, msieve (portable OPT_FLAGS), redumis (KaMIS), gclc; amd64-only (gwnum/x86 asm; CI and production are amd64): srsieve2, sllr64 (LLR), pfgw64 (OpenPFGW). - walnut_build: Walnut v7.1.0 at /opt/walnut (automatic-sequence decision procedure; bookworm JRE). - julia_build: Julia 1.12.7 + Oscar 1.8.1/Hecke 0.39.22, fully precompiled offline-usable depot at /opt/julia-depot. Docs policy change: /opt/docs is now DOWNLOADED at image build by the docs_fetch stage -- verbatim upstream text files at pins matching the installed revisions (shared ARGs where the install is ARG-pinned) -- and the vendored apn/lean/docs/ tree is gone. PDF-only or unpinnable docs mean the tool ships undocumented. Dropped as not worth the complexity (fragile builds, unpinnable deps, cross-package interactions, abandonware, or redundant coverage): QEPCAD B, REDUCE/Redlog, dReal4, ganak, d4, yafu, cado-nfs, twee, MetiTarski, SDPA-GMP, ncpol2sdpa, gudhi, latte-integrale, genreg, snarkhunter, PHCpack/phcpy, Ibex, CAPD, PySR, GAP package suite (conda GAP already ships SmallGrp + CTblLib), soplex. Prompt and the hardcoded contract suite extended to match (new smokes: kissat->drat-trim certificate roundtrip, GAP SmallGroup, SCIP MIQCP, vampire refutation, Walnut on Thue-Morse, offline Oscar load); version 0.1.10rc2 for fresh image tags. Contract suite: 116 passed, 3 skipped (the amd64-only binaries, on an arm64 host). --- apn/__init__.py | 2 +- apn/lean/Dockerfile | 373 +- apn/lean/compute-env.yaml | 3 + apn/lean/docs/4ti2/4ti2-manual.txt | 1568 --------- apn/lean/docs/4ti2/LICENSE | 339 -- apn/lean/docs/csdp/LICENSE | 237 -- apn/lean/docs/csdp/csdp-user-guide.txt | 335 -- apn/lean/docs/loogle/LICENSE | 71 - apn/lean/docs/loogle/loogle.md | 84 - apn/lean/docs/lrslib/LICENSE | 339 -- apn/lean/docs/lrslib/lrs-userguide.md | 1065 ------ apn/lean/docs/msolve/LICENSE | 339 -- apn/lean/docs/msolve/msolve-tutorial.txt | 742 ---- apn/lean/docs/nauty/COPYRIGHT | 44 - apn/lean/docs/nauty/LICENSE | 202 -- apn/lean/docs/nauty/nauty-guide.txt | 2039 ----------- apn/lean/docs/normaliz/LICENSE | 682 ---- apn/lean/docs/normaliz/normaliz-manual.txt | 3604 -------------------- apn/lean/docs/plantri/LICENSE | 202 -- apn/lean/docs/plantri/plantri-guide.txt | 1579 --------- apn/lean/docs/polymake/LICENSE | 361 -- apn/lean/docs/polymake/polymake.md | 1872 ---------- apn/lean/docs/prover9/LICENSE | 339 -- apn/lean/docs/prover9/prover9-manual.md | 3218 ----------------- apn/lean/docs/python-flint/LICENSE | 22 - apn/lean/docs/python-flint/python-flint.md | 375 -- apn/lean/docs/regina/LICENSE | 470 --- apn/lean/docs/regina/regina-python.md | 948 ----- apn/lean/docs/snappy/LICENSE | 351 -- apn/lean/docs/snappy/snappy.md | 1238 ------- apn/prompts.py | 9 +- apn/redteam.py | 2 +- pyproject.toml | 2 +- tests/test_agent_image.py | 163 +- tests/test_tools.py | 10 +- uv.lock | 2 +- 36 files changed, 529 insertions(+), 22702 deletions(-) delete mode 100644 apn/lean/docs/4ti2/4ti2-manual.txt delete mode 100644 apn/lean/docs/4ti2/LICENSE delete mode 100644 apn/lean/docs/csdp/LICENSE delete mode 100644 apn/lean/docs/csdp/csdp-user-guide.txt delete mode 100644 apn/lean/docs/loogle/LICENSE delete mode 100644 apn/lean/docs/loogle/loogle.md delete mode 100644 apn/lean/docs/lrslib/LICENSE delete mode 100644 apn/lean/docs/lrslib/lrs-userguide.md delete mode 100644 apn/lean/docs/msolve/LICENSE delete mode 100644 apn/lean/docs/msolve/msolve-tutorial.txt delete mode 100644 apn/lean/docs/nauty/COPYRIGHT delete mode 100644 apn/lean/docs/nauty/LICENSE delete mode 100644 apn/lean/docs/nauty/nauty-guide.txt delete mode 100644 apn/lean/docs/normaliz/LICENSE delete mode 100644 apn/lean/docs/normaliz/normaliz-manual.txt delete mode 100644 apn/lean/docs/plantri/LICENSE delete mode 100644 apn/lean/docs/plantri/plantri-guide.txt delete mode 100644 apn/lean/docs/polymake/LICENSE delete mode 100644 apn/lean/docs/polymake/polymake.md delete mode 100644 apn/lean/docs/prover9/LICENSE delete mode 100644 apn/lean/docs/prover9/prover9-manual.md delete mode 100644 apn/lean/docs/python-flint/LICENSE delete mode 100644 apn/lean/docs/python-flint/python-flint.md delete mode 100644 apn/lean/docs/regina/LICENSE delete mode 100644 apn/lean/docs/regina/regina-python.md delete mode 100644 apn/lean/docs/snappy/LICENSE delete mode 100644 apn/lean/docs/snappy/snappy.md diff --git a/apn/__init__.py b/apn/__init__.py index 11fd3150..398df821 100644 --- a/apn/__init__.py +++ b/apn/__init__.py @@ -1,4 +1,4 @@ __all__ = ["__version__"] -__version__ = "0.1.10rc1" +__version__ = "0.1.10rc2" diff --git a/apn/lean/Dockerfile b/apn/lean/Dockerfile index 92b64eb4..8c16ce77 100644 --- a/apn/lean/Dockerfile +++ b/apn/lean/Dockerfile @@ -13,11 +13,13 @@ # One locked conda-forge env at /opt/env (python + Sage + # the python stack + solver binaries; spec in # compute-env.yaml, built in `compute_build`), apt tools -# conda-forge lacks, source-built solvers (`solvers_build`), -# the Loogle Mathlib-search CLI (`loogle_build`), and -# vendored per-tool docs at /opt/docs. Deliberately contains -# NO verifier tooling (no comparator, no lean4export, no -# landrun). +# conda-forge lacks, source-built and release-pinned solvers +# (`solvers_build`), Walnut (`walnut_build`), Julia with +# OSCAR/Hecke (`julia_build`), the Loogle Mathlib-search CLI +# (`loogle_build`), and per-tool docs downloaded from pinned +# upstream sources (`docs_fetch`) at /opt/docs. Deliberately +# contains NO verifier tooling (no comparator, no +# lean4export, no landrun). # - comparator -- the trusted verifier: base + the Comparator binary + the # lean4export binary + landrun + the pristine workspace tree. # Replaces the former `compile` + `scorer` pair: the @@ -71,6 +73,22 @@ # axioms), the library test suite, and repo tooling/docs/.git never reach the # agent's sandbox, so there is no contamination to strip after the fact. +# Shared pins: tools whose install AND whose /opt/docs documentation (the +# `docs_fetch` stage) must come from the SAME revision. Declared once here; +# stages redeclare `ARG ` (no value) to inherit these defaults, so a +# bump moves the tool and its docs together. Docs for tools pinned elsewhere +# (compute-env.yaml, bookworm's package table, the pip layer) hardcode the +# matching revision in docs_fetch with a comment naming the pin they mirror. +ARG MSOLVE_VERSION=0.10.1 +ARG PLANTRI_VERSION=55 +ARG DRATTRIM_VERSION=v05.22.2023 +ARG BREAKID_VERSION=3.1.3 +ARG SMS_VERSION=v2.1.1 +ARG CAKE_LPR_COMMIT=a36874a8b750b43fe4b385b8ddbf5b033e46a3fa +ARG KAMIS_VERSION=v3.2 +ARG GCLC_VERSION=v2026.1 +ARG MSIEVE_VERSION=1.53 + # --------------------------------------------------------------------------- # # Builder: clone + build the FC library (everything here is discarded). # # --------------------------------------------------------------------------- # @@ -246,8 +264,10 @@ FROM debian:bookworm-slim AS compute_build ENV DEBIAN_FRONTEND=noninteractive +# build-essential: graphillion has no cp313 wheel, so its pip install below +# compiles the sdist (stage-local; the compiler does not ship). RUN apt-get update && apt-get install -y --no-install-recommends \ - curl ca-certificates bzip2 \ + curl ca-certificates bzip2 build-essential \ && rm -rf /var/lib/apt/lists/* ARG MICROMAMBA_VERSION=2.9.0 @@ -260,21 +280,32 @@ COPY compute-env.yaml /tmp/compute-env.yaml RUN micromamba create -y -p /opt/env -f /tmp/compute-env.yaml \ && micromamba clean -afy -# PyPI-only packages (prebuilt wheels), into the same env. snappy is SnapPy -# (3-manifold topology), not the compression lib. +# PyPI-only packages, into the same env. snappy is SnapPy (3-manifold +# topology), not the compression lib. pyscipopt's wheel bundles libscip +# (SCIP via conda is impossible: every scip/soplex build wants a boost newer +# than the sage stack's pin). graphillion compiles from sdist (no cp313 +# wheel; verified clean on py3.13, both arches). RUN /opt/env/bin/pip install --no-cache-dir \ python-sat==1.9.dev15 \ cvc5==1.3.4 \ ortools==9.15.6755 \ snappy==3.3.2 \ + pysindy==2.1.0 \ + hypothesis==6.165.10 \ + libsemigroups_pybind11==1.4.4 \ + pymanopt==2.2.1 \ + graphillion==2.1 \ + pyscipopt==6.2.1 \ && find /opt/env -name '__pycache__' -type d -prune -exec rm -rf {} + # --------------------------------------------------------------------------- # # solvers_build: tools with no conda-forge or bookworm packaging, built from # -# pinned sources (plus the pinned official cvc5 static binary -- its PyPI # -# wheel in compute_build carries only the python API). Everything lands in # -# /out/bin and links only libc/libm from the shared bookworm userland (flint/ # -# gmp/mpfr are linked statically), so the binaries drop straight into agent. # +# pinned sources (plus pinned official release binaries: cvc5 static, whose # +# PyPI wheel in compute_build carries only the python API; vampire; cake_lpr; # +# and the x86-only LLR/PFGW primality provers). Everything lands in /out/bin # +# and links only the libc family, libstdc++, and zlib from the shared # +# bookworm userland (flint/gmp/mpfr are linked statically), so the binaries # +# drop straight into agent. # # --------------------------------------------------------------------------- # FROM debian:bookworm-slim AS solvers_build @@ -282,6 +313,8 @@ ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y --no-install-recommends \ curl ca-certificates build-essential unzip m4 \ + cmake git subversion p7zip perl zlib1g-dev \ + libboost-graph-dev libboost-program-options-dev \ libgmp-dev libmpfr-dev \ && rm -rf /var/lib/apt/lists/* \ && mkdir -p /out/bin @@ -296,7 +329,7 @@ RUN curl -sSfL "https://github.com/arminbiere/kissat/archive/refs/tags/${KISSAT_ && rm -rf /tmp/kissat-* # plantri: planar-graph generator (Brinkmann & McKay). -ARG PLANTRI_VERSION=55 +ARG PLANTRI_VERSION RUN curl -sSfL "https://users.cecs.anu.edu.au/~bdm/plantri/plantri${PLANTRI_VERSION}.tar.gz" \ | tar xz -C /tmp \ && cd /tmp/plantri* \ @@ -319,7 +352,7 @@ RUN curl -sSfL "https://github.com/ai4reason/Prover9/archive/${PROVER9_COMMIT}.t # FLINT >= 3, which bookworm lacks -- both are built here, FLINT static so # nothing but the msolve binaries ship. ARG FLINT_VERSION=3.6.0 -ARG MSOLVE_VERSION=0.10.1 +ARG MSOLVE_VERSION RUN curl -sSfL "https://github.com/flintlib/flint/releases/download/v${FLINT_VERSION}/flint-${FLINT_VERSION}.tar.gz" \ | tar xz -C /tmp \ && cd /tmp/flint-* \ @@ -345,6 +378,201 @@ RUN arch="$(uname -m)" \ && install -m 755 /tmp/cvc5/*/bin/cvc5 /out/bin/cvc5 \ && rm -rf /tmp/cvc5 /tmp/cvc5.zip +# vampire: superposition first-order prover + finite-model builder (--mode +# fmb), official pinned release binaries (link only libc/libstdc++). +ARG VAMPIRE_VERSION=v5.1.0 +RUN arch="$(uname -m)" \ + && case "$arch" in \ + x86_64) z=vampire-Linux-X64.zip; sha=495828dc76cb17a27080d62dedce755e46de96f47f06f5f0ad4be9cdaf6f968f ;; \ + aarch64) z=vampire-Linux-ARM64.zip; sha=7abc39224fdf41bdb2c241f8b180a80b7c1a4bce1e46dc79df02cfea2798ad5c ;; \ + *) echo "unsupported arch $arch" >&2; exit 1 ;; \ + esac \ + && curl -sSfL -o /tmp/vampire.zip \ + "https://github.com/vprover/vampire/releases/download/${VAMPIRE_VERSION}/${z}" \ + && echo "${sha} /tmp/vampire.zip" | sha256sum -c - \ + && unzip -q /tmp/vampire.zip -d /tmp/vampire \ + && install -m 755 "$(find /tmp/vampire -type f -name vampire)" /out/bin/vampire \ + && rm -rf /tmp/vampire /tmp/vampire.zip + +# drat-trim + lrat-check: proof checkers for SAT solvers' UNSAT certificates +# (DRAT from kissat/cryptominisat; DRAT->LRAT conversion). +ARG DRATTRIM_VERSION +RUN curl -sSfL "https://github.com/marijnheule/drat-trim/archive/refs/tags/${DRATTRIM_VERSION}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/drat-trim-* \ + && make \ + && install -m 755 drat-trim lrat-check /out/bin/ \ + && rm -rf /tmp/drat-trim-* + +# cake_lpr: formally verified LRAT proof checker (CakeML); built from the +# repo's pre-generated per-arch assembly with one gcc call. +ARG CAKE_LPR_COMMIT +RUN curl -sSfL "https://github.com/tanyongkiam/cake_lpr/archive/${CAKE_LPR_COMMIT}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/cake_lpr-* \ + && case "$(uname -m)" in x86_64) s=cake_lpr.S ;; aarch64) s=cake_lpr_arm8.S ;; esac \ + && gcc -O2 -std=c99 basis_ffi.c "$s" -o /out/bin/cake_lpr \ + && rm -rf /tmp/cake_lpr-* + +# BreakID: static CNF symmetry breaking (preprocessor for SAT searches). +ARG BREAKID_VERSION +RUN git clone --depth 1 --branch "release/${BREAKID_VERSION}" \ + https://github.com/meelgroup/breakid /tmp/breakid \ + && cmake -S /tmp/breakid -B /tmp/breakid/build -DCMAKE_BUILD_TYPE=Release \ + && cmake --build /tmp/breakid/build -j"$(nproc)" \ + && install -m 755 /tmp/breakid/build/breakid /out/bin/breakid \ + && rm -rf /tmp/breakid + +# SMS (smsg): SAT-modulo-symmetries graph search -- find/enumerate graphs with +# a property, modulo isomorphism. CaDiCaL is bundled as a pinned submodule. +ARG SMS_VERSION +RUN git clone --depth 1 --branch "${SMS_VERSION}" --recurse-submodules \ + https://github.com/markirch/sat-modulo-symmetries /tmp/sms \ + && cd /tmp/sms/cadical_sms && ./configure -fPIC && make -j"$(nproc)" \ + && cd /tmp/sms \ + # static boost so the binary keeps to the shared bookworm userland + && cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DBoost_USE_STATIC_LIBS=ON \ + && cmake --build build -j"$(nproc)" \ + && install -m 755 build/src/smsg /out/bin/smsg \ + && rm -rf /tmp/sms + +# march_cu: cube-and-conquer splitter for hard SAT instances (Heule's CnC; +# no tags upstream, commit-pinned). -fcommon: pre-C99 tentative definitions. +ARG MARCH_CU_COMMIT=705b60c6491ef2b61988b3ce6ac674be1b90571d +RUN curl -sSfL "https://github.com/marijnheule/CnC/archive/${MARCH_CU_COMMIT}.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/CnC-*/march_cu \ + && make CFLAGS='-O3 -fno-strict-aliasing -Wall -DNDEBUG -fcommon' \ + && install -m 755 march_cu /out/bin/march_cu \ + && rm -rf /tmp/CnC-* + +# msieve: SIQS/NFS integer factorization past gmp-ecm's reach. OPT_FLAGS +# overrides the Makefile's -march=native so the binary is portable. +ARG MSIEVE_VERSION +RUN curl -sSfL "https://downloads.sourceforge.net/project/msieve/msieve/Msieve%20v${MSIEVE_VERSION}/msieve$(echo "${MSIEVE_VERSION}" | tr -d .)_src.tar.gz" \ + | tar xz -C /tmp \ + && cd /tmp/msieve-* \ + && make all -j"$(nproc)" OPT_FLAGS='-O3 -fomit-frame-pointer -D_FILE_OFFSET_BITS=64 -DNDEBUG' \ + && install -m 755 msieve /out/bin/msieve \ + && rm -rf /tmp/msieve-* + +# redumis (KaMIS): near-optimal maximum independent sets at scales exact +# solvers can't reach (KaHIP is vendored in the release tarball). +ARG KAMIS_VERSION +RUN curl -sSfL "https://github.com/KarlsruheMIS/KaMIS/archive/refs/tags/${KAMIS_VERSION}.tar.gz" \ + | tar xz -C /tmp \ + && cmake -S /tmp/KaMIS-* -B /tmp/kamis-build -DCMAKE_BUILD_TYPE=Release \ + && cmake --build /tmp/kamis-build -j"$(nproc)" --target redumis \ + && install -m 755 /tmp/kamis-build/redumis /out/bin/redumis \ + && rm -rf /tmp/KaMIS-* /tmp/kamis-build + +# gclc: automated Euclidean geometry proving (area/Wu methods; CLI only). +ARG GCLC_VERSION +RUN git clone --depth 1 --branch "${GCLC_VERSION}" https://github.com/janicicpredrag/gclc /tmp/gclc \ + && cmake -S /tmp/gclc -B /tmp/gclc/build -DCMAKE_BUILD_TYPE=Release -Dgui=OFF \ + && cmake --build /tmp/gclc/build -j"$(nproc)" \ + && install -m 755 /tmp/gclc/build/gclc /out/bin/gclc \ + && rm -rf /tmp/gclc + +# The special-form primality toolchain, amd64 images only (CI/production): +# srsieve2 sieves k*b^n+-c candidate grids (mtsieve suite; SourceForge SVN, +# revision-pinned; its makefile only knows x86 and 32-bit ARM), then sllr64 +# (LLR) and pfgw64 (OpenPFGW) prove primality at 10^5..10^7 digits (gwnum is +# x86-64 assembly -- no arm route exists). +ARG MTSIEVE_SVN_REV=469 +ARG LLR_VERSION=407 +ARG PFGW_VERSION=4.1.8 +RUN if [ "$(uname -m)" = x86_64 ]; then \ + svn checkout -q -r "${MTSIEVE_SVN_REV}" https://svn.code.sf.net/p/mtsieve/svn/ /tmp/mtsieve \ + && cd /tmp/mtsieve \ + && make -j"$(nproc)" srsieve2 \ + && install -m 755 srsieve2 /out/bin/srsieve2 \ + && rm -rf /tmp/mtsieve; \ + fi +RUN if [ "$(uname -m)" = x86_64 ]; then \ + curl -sSfL -o /tmp/llr.zip "https://jpenne.free.fr/llr4/llr${LLR_VERSION}slinux64.zip" \ + && echo "b92424d85d0d37788bb33613ec1af2b6d5cb1f5ce37be5ed062b0aad604a6ab3 /tmp/llr.zip" | sha256sum -c - \ + && unzip -q /tmp/llr.zip -d /tmp/llr \ + && install -m 755 "$(find /tmp/llr -type f -name sllr64)" /out/bin/sllr64 \ + && curl -sSfL -o /tmp/pfgw.7z "https://downloads.sourceforge.net/project/openpfgw/pfgw_linux_${PFGW_VERSION}.7z" \ + && echo "aadf885e2d6489866bb7eeea2ba3f75a3fa02e679f1d6a86fd2632e042a99c99 /tmp/pfgw.7z" | sha256sum -c - \ + && 7zr x -o/tmp/pfgw /tmp/pfgw.7z >/dev/null \ + && install -m 755 /tmp/pfgw/pfgw64 /out/bin/pfgw64 \ + && rm -rf /tmp/llr /tmp/llr.zip /tmp/pfgw /tmp/pfgw.7z; \ + fi + +# --------------------------------------------------------------------------- # +# walnut_build: Walnut, the decision procedure for automatic sequences / # +# base-k digit statements (Buechi arithmetic). Java; built once with the # +# repo's own gradle wrapper, shipped as the /opt/walnut tree and run via # +# upstream's launcher: /opt/walnut/walnut.sh (JRE comes from the agent # +# stage's default-jre-headless). # +# --------------------------------------------------------------------------- # +FROM debian:bookworm-slim AS walnut_build + +ENV DEBIAN_FRONTEND=noninteractive + +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl ca-certificates openjdk-17-jdk-headless git \ + && rm -rf /var/lib/apt/lists/* + +# Upstream's build.sh is its gradle invocation + chmod, followed by an +# interactive "Press enter" prompt that exits 1 in a non-interactive build -- +# so run those two commands directly. +ARG WALNUT_VERSION=v7.1.0 +RUN curl -sSfL "https://github.com/Walnut-Theorem-Prover/Walnut/archive/refs/tags/${WALNUT_VERSION}.tar.gz" \ + | tar xz -C /opt \ + && mv /opt/Walnut-* /opt/walnut \ + && cd /opt/walnut \ + && ./gradlew clean customFatJar \ + && chmod +x walnut.sh \ + && rm -rf /root/.gradle + +# --------------------------------------------------------------------------- # +# julia_build: Julia + OSCAR/Hecke (computer algebra: Galois groups, number # +# fields, group theory) as a fully precompiled, offline-usable depot. The # +# multi-target JULIA_CPU_TARGET (the same lists the official binaries use) # +# makes the baked pkgimages load on any deploy CPU. NEVER build this stage # +# under qemu emulation: precompilation crashes there (native-only, both # +# arches verified for artifact coverage). # +# --------------------------------------------------------------------------- # +FROM debian:bookworm-slim AS julia_build + +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl ca-certificates \ + && rm -rf /var/lib/apt/lists/* + +# sha256s from https://julialang-s3.julialang.org/bin/checksums/julia-1.12.7.sha256 +ARG JULIA_VERSION=1.12.7 +RUN arch="$(uname -m)" \ + && case "$arch" in \ + x86_64) a=x64/1.12/julia-${JULIA_VERSION}-linux-x86_64.tar.gz; \ + sha=4e7e9e776634d24835250de67cde39b0d4af15bc432eb20697e6be6c28ea69e8 ;; \ + aarch64) a=aarch64/1.12/julia-${JULIA_VERSION}-linux-aarch64.tar.gz; \ + sha=9243c0b524c7f300883240a1ee5ea3916a30e070bff718acf8ccaee31a731ef2 ;; \ + *) echo "unsupported arch $arch" >&2; exit 1 ;; \ + esac \ + && curl -fsSL "https://julialang-s3.julialang.org/bin/linux/${a}" -o /tmp/julia.tar.gz \ + && echo "${sha} /tmp/julia.tar.gz" | sha256sum -c - \ + && mkdir -p /opt/julia \ + && tar -xzf /tmp/julia.tar.gz -C /opt/julia --strip-components=1 \ + && rm /tmp/julia.tar.gz + +ENV JULIA_DEPOT_PATH=/opt/julia-depot +ARG OSCAR_VERSION=1.8.1 +ARG HECKE_VERSION=0.39.22 +RUN case "$(uname -m)" in \ + x86_64) export JULIA_CPU_TARGET='generic;sandybridge,-xsaveopt,clone_all;haswell,-rdrnd,base(1);x86-64-v4,-rdrnd,base(1)' ;; \ + aarch64) export JULIA_CPU_TARGET='generic;cortex-a57;thunderx2t99;carmel,clone_all;apple-m1,base(3);neoverse-512tvb,-rand,-fpac,base(3)' ;; \ + esac \ + && /opt/julia/bin/julia -e "using Pkg; Pkg.add([ \ + PackageSpec(name=\"Oscar\", version=\"${OSCAR_VERSION}\"), \ + PackageSpec(name=\"Hecke\", version=\"${HECKE_VERSION}\")]); \ + Pkg.precompile(); Pkg.gc()" \ + # The depot must be complete: loading may not touch the network. + && JULIA_PKG_OFFLINE=true /opt/julia/bin/julia -e \ + 'using Oscar; using Hecke; println("Oscar ", Oscar.VERSION_NUMBER)' + # --------------------------------------------------------------------------- # # loogle_build: the Loogle type-pattern Mathlib search CLI. Upstream's # # "Running locally" contract: the binary is dependency-free, must merely be # @@ -365,6 +593,89 @@ RUN git clone https://github.com/nomeata/loogle.git /opt/loogle \ && cd /workspace/leanproject \ && lake env /opt/loogle/.lake/build/bin/loogle --module Mathlib "Nat.Prime" > /dev/null +# --------------------------------------------------------------------------- # +# docs_fetch: in-sandbox references at /opt/docs/, DOWNLOADED at build # +# from pinned sources (never vendored in the repo, never PDFs, always the # +# upstream files verbatim). Each fetch is pinned to the revision the image # +# actually installs: shared ARGs (top of file) where the install is ARG- # +# pinned, hardcoded matching revisions (with the mirrored pin named in a # +# comment) where the install pin lives in compute-env.yaml / bookworm / the # +# pip layer. Tools whose only docs are PDFs or mutable webpages ship # +# undocumented (their --help still works). # +# --------------------------------------------------------------------------- # +FROM debian:bookworm-slim AS docs_fetch + +ENV DEBIAN_FRONTEND=noninteractive + +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl ca-certificates git \ + && rm -rf /var/lib/apt/lists/* + +# Single-file fetches from pinned raw URLs. +ARG DRATTRIM_VERSION +ARG BREAKID_VERSION +ARG CAKE_LPR_COMMIT +ARG KAMIS_VERSION +ARG GCLC_VERSION +ARG MSOLVE_VERSION +# Must equal loogle_build's LOOGLE_COMMIT. +ARG LOOGLE_DOCS_COMMIT=9f11169aaebf1ed1e7dcc4077f2aafe0fcf66fd0 +RUN set -e; \ + fetch() { mkdir -p "/opt/docs/$1" && curl -sSfL -o "/opt/docs/$1/$2" "$3"; }; \ + fetch loogle README.md "https://raw.githubusercontent.com/nomeata/loogle/${LOOGLE_DOCS_COMMIT}/README.md"; \ + fetch loogle blurb.md "https://raw.githubusercontent.com/nomeata/loogle/${LOOGLE_DOCS_COMMIT}/blurb.md"; \ + fetch msolve msolve-tutorial.tex "https://raw.githubusercontent.com/algebraic-solving/msolve/v${MSOLVE_VERSION}/doc/msolve-tutorial.tex"; \ + fetch drat-trim README.md "https://raw.githubusercontent.com/marijnheule/drat-trim/${DRATTRIM_VERSION}/README.md"; \ + fetch breakid README.md "https://raw.githubusercontent.com/meelgroup/breakid/release/${BREAKID_VERSION}/README.md"; \ + fetch cake_lpr README.md "https://raw.githubusercontent.com/tanyongkiam/cake_lpr/${CAKE_LPR_COMMIT}/README.md"; \ + fetch kamis README.md "https://raw.githubusercontent.com/KarlsruheMIS/KaMIS/${KAMIS_VERSION}/README.md"; \ + fetch gclc gclc_man.tex "https://raw.githubusercontent.com/janicicpredrag/gclc/${GCLC_VERSION}/manual/gclc_man.tex"; \ + # matches bookworm coinor-csdp 6.2.0-4 + fetch csdp csdpuser.tex "https://raw.githubusercontent.com/coin-or/Csdp/releases/6.2.0/doc/csdpuser.tex"; \ + # matches the pip layer's graphillion==2.1 + fetch graphillion README.md "https://raw.githubusercontent.com/takemaru/graphillion/v2.1/README.md"; \ + # matches compute-env.yaml 4ti2=1.6.15 + for f in 4ti2_manual 4ti2_manual_beginner 4ti2_manual_advanced 4ti2_manual_ref 4ti2_manual_api; do \ + fetch 4ti2 "$f.tex" "https://raw.githubusercontent.com/4ti2/4ti2/Release_1_6_15/doc/$f.tex"; \ + done + +# Tag-pinned clones where the docs are a file set. +ARG SMS_VERSION +RUN set -e; \ + clonedocs() { git clone -q --depth 1 --branch "$2" "$1" /tmp/d && mkdir -p "/opt/docs/$3"; }; \ + # matches solvers_build's SMS_VERSION + clonedocs https://github.com/markirch/sat-modulo-symmetries "${SMS_VERSION}" sms \ + && cp /tmp/d/docs/*.md /opt/docs/sms/ && rm -rf /tmp/d; \ + # matches compute-env.yaml normaliz=3.11.0 + clonedocs https://github.com/Normaliz/Normaliz v3.11.0 normaliz \ + && cp /tmp/d/doc/*.tex /tmp/d/README.md /opt/docs/normaliz/ && rm -rf /tmp/d; \ + # matches the pip layer's snappy==3.3.2 (SnapPy) + clonedocs https://github.com/3-manifolds/SnapPy 3.3.2_as_released snappy \ + && cp /tmp/d/doc_src/*.rst /opt/docs/snappy/ && rm -rf /tmp/d; \ + # matches compute-env.yaml python-flint=0.8.0 + clonedocs https://github.com/flintlib/python-flint 0.8.0 python-flint \ + && cp /tmp/d/doc/source/*.rst /opt/docs/python-flint/ && rm -rf /tmp/d; \ + # matches bookworm regina-normal 7.3 (handbook source; DocBook is text) + clonedocs https://github.com/regina-normal/regina regina-7.3 regina \ + && cp /tmp/d/qtui/doc/regina/*.docbook /opt/docs/regina/ && rm -rf /tmp/d + +# Tarball-shipped docs (same tarballs the installs use). +ARG PLANTRI_VERSION +RUN set -e; \ + mkdir -p /opt/docs/plantri /opt/docs/lrslib /opt/docs/msieve; \ + curl -sSfL "https://users.cecs.anu.edu.au/~bdm/plantri/plantri${PLANTRI_VERSION}.tar.gz" | tar xz -C /tmp \ + && cp /tmp/plantri*/plantri-guide.txt /opt/docs/plantri/ && rm -rf /tmp/plantri*; \ + # matches compute-env.yaml lrslib=73.a + curl -sSfL "https://cgm.cs.mcgill.ca/~avis/C/lrslib/archive/lrslib-073a.tar.gz" | tar xz -C /tmp \ + && cp -r /tmp/lrslib-073a/man/html /opt/docs/lrslib/man-html \ + && cp /tmp/lrslib-073a/README /opt/docs/lrslib/ && rm -rf /tmp/lrslib-073a; \ + curl -sSfL "https://downloads.sourceforge.net/project/msieve/msieve/Msieve%20v1.53/msieve153_src.tar.gz" | tar xz -C /tmp \ + && cp /tmp/msieve-*/Readme* /opt/docs/msieve/ && rm -rf /tmp/msieve-* + +# Walnut's per-command help ships inside the same build the image runs. +COPY --from=walnut_build /opt/walnut/README.md /opt/docs/walnut/README.md +COPY --from=walnut_build ["/opt/walnut/Help Documentation/Commands", "/opt/docs/walnut/commands"] + # --------------------------------------------------------------------------- # # agent: the agent's workspace. Layer order is big/stable first (the conda # # env), then apt, then the small solver binaries, then Loogle, then docs # @@ -380,20 +691,36 @@ COPY --from=compute_build /opt/env /opt/env ENV PATH=/opt/env/bin:$PATH RUN echo 'export PATH=/opt/env/bin:$PATH' > /etc/profile.d/compute-env.sh +# Julia with the precompiled OSCAR/Hecke depot (see julia_build). The depot +# path must match the build-time one or every load re-precompiles. +COPY --from=julia_build /opt/julia /opt/julia +COPY --from=julia_build /opt/julia-depot /opt/julia-depot +ENV JULIA_DEPOT_PATH=/opt/julia-depot +RUN ln -s /opt/julia/bin/julia /usr/local/bin/julia \ + && echo 'export JULIA_DEPOT_PATH=/opt/julia-depot' > /etc/profile.d/julia.sh + # Tools conda-forge lacks, from bookworm: polymake (polyhedral geometry), # Macaulay2 (commutative algebra), regina-normal (low-dimensional topology; # `regina-python`), cryptominisat (SAT, newer here than conda-forge's), -# coinor-csdp (semidefinite programming, `csdp`), jq + ripgrep for the bash -# tool (git is already in `base`), libmpfr6 (msolve's one non-static runtime -# link besides gmp, which base's libgmp-dev already provides). +# coinor-csdp (semidefinite programming, `csdp`), topcom (triangulations), +# cadabra2 (tensor algebra), minizinc (CP modeling), berkeley-abc (Boolean +# networks), eprover (first-order ATP), mpsolve (certified polynomial roots), +# default-jre-headless (runs Walnut), jq + ripgrep for the bash tool (git is +# already in `base`), libmpfr6 (msolve's one non-static runtime link besides +# gmp, which base's libgmp-dev already provides). RUN apt-get update && apt-get install -y --no-install-recommends \ polymake macaulay2 regina-normal cryptominisat coinor-csdp \ - jq ripgrep libmpfr6 \ + topcom cadabra2 minizinc berkeley-abc eprover mpsolve \ + default-jre-headless jq ripgrep libmpfr6 \ && rm -rf /var/lib/apt/lists/* -# Source-built solvers (kissat, plantri, prover9/mace4, msolve, cvc5). +# Source-built and release-pinned solver binaries (see solvers_build). COPY --from=solvers_build /out/bin/ /usr/local/bin/ +# Walnut (automatic-sequence decision procedure): upstream's own tree and +# launcher, run as /opt/walnut/walnut.sh (java from apt above). +COPY --from=walnut_build /opt/walnut /opt/walnut + # Loogle: the dependency-free binary, plus the Mathlib search index it baked # next to Mathlib.olean (COPY preserves mtimes, and this stage shares base's # layers with loogle_build, so the index stays valid; were it ever judged @@ -405,10 +732,10 @@ COPY --from=loogle_build \ /workspace/leanproject/.lake/packages/mathlib/.lake/build/lib/lean/Mathlib.loogle-index \ /workspace/leanproject/.lake/packages/mathlib/.lake/build/lib/lean/Mathlib.loogle-index -# In-sandbox references (the sandbox has no network): vendored, version-matched -# docs for the tools whose syntax the agent is unlikely to know cold. Last: -# docs churn more than any layer above. -COPY docs /opt/docs +# In-sandbox references (the sandbox has no network): version-matched upstream +# docs, downloaded at build (see docs_fetch). Last: docs churn more than any +# layer above. +COPY --from=docs_fetch /opt/docs /opt/docs CMD ["sleep", "infinity"] diff --git a/apn/lean/compute-env.yaml b/apn/lean/compute-env.yaml index 4c83b89d..f9728872 100644 --- a/apn/lean/compute-env.yaml +++ b/apn/lean/compute-env.yaml @@ -37,6 +37,9 @@ dependencies: # solvers (binary + python bindings) - z3-solver=5.1.0.0 - glpk=5.0 + - clingo=5.8.2 # ASP: clingo binary + python module + - cvxpy=1.9.2 # convex-optimization modeling front end + - clarabel=0.11.1 # lattice reduction - fpylll=0.6.4 # number theory CLI tools diff --git a/apn/lean/docs/4ti2/4ti2-manual.txt b/apn/lean/docs/4ti2/4ti2-manual.txt deleted file mode 100644 index 111546e0..00000000 --- a/apn/lean/docs/4ti2/4ti2-manual.txt +++ /dev/null @@ -1,1568 +0,0 @@ - - - -Chapter 1 - -Beginner’s guide - -In this part, we use a few sample problems to introduce you to the basic functionality -of 4ti2. After working through this part, you should know about linear systems and -their encodings in 4ti2, and should be able to do computations using the following -functions: - - • qsolve, rays, circuits - - • zsolve, hilbert, graver, ppi - - • minimize, groebner, normalform - - • genmodel, markov - - - -1.1 Linear systems and their encodings - -In this section you learn about the data structure linear system and how it is -specified in 4ti2. - - -1.1.1 Linear systems and integer linear systems - -In 4ti2, a linear system is defined by d constraints Ax ∼ b in n unknowns x, where -each constraint is either ≤, = or ≥, that is ∼ ∈ {≤, =, ≥}d . Moreover, one may - - 5 -1.1. Linear systems and their encodings 6 - - -specify sign constraints on the variables that need to be respected in an explicit -continuous/integer representation of all solutions. -There is no particular difference in 4ti2 between a linear system and an integer -linear system. Currently, the user chooses between one of the two by calling the -appropriate functions on the linear system. - - -1.1.2 Specifying a linear system in 4ti2 - -In order to use a linear system as input, we need to specify its parts to 4ti2. As our -running example, take - ! ! - 1 1 1 1 ≤ 6 - x - 1 2 3 4 ≤ 10 - -with sign constraints (1, 2, 2, 0), which we will explain below. -First, we have to give our problem a project name, say PROJECT. - - • The matrix A has to be put into the file PROJECT.mat. - - 2 4 - 1 1 1 1 - 1 2 3 4 - - • The relations ∼ then have to be specified in PROJECT.rel. - - 1 2 - < < - - • The right-hand side vector goes into PROJECT.rhs. - - 1 2 - 6 10 - - • And finally, the sign constraints end up in PROJECT.sign. - - 1 4 - 1 2 2 0 -Chapter 1. Beginner’s guide 7 - - -Note. - - • The input files all have the format of a matrix, preceded by the matrix di- - mensions. As the dimensions already specify how many symbols have to be - read, the matrix could also be given in only one line or even in many lines of - different lengths. - - • In 4ti2 version 1.3.1 and later, all appearing numbers have to be integers. - - • Consequently, this implies that, at the moment, qsolve only supports homoge- - neous linear systems, that is systems with b = 0, since minimal inhomogeneous - solutions could have rational components. - - -1.1.3 What does an explicit solution to linear systems look - like? - -If the system is solved over R (using qsolve), 4ti2 returns two sets of integer -vectors: - - • a set H of support-minimal homogeneous solutions, and - - • a set F defining the linear vector space the solution set lives in. - -As only homogeneous linear systems are supported in this version of 4ti2, no list of -minimal inhomogeneous solutions is computed. Any solution z of the linear system -can now be written as - X X - z= αj hj + βk fk (1.1) - -with hj ∈ H, fk ∈ F , and αj ≥ 0. -If the system is solved over Z (using zsolve), 4ti2 returns three sets of integer -vectors: - - • a set H of minimal homogeneous integer solutions, - - • a set I of minimal inhomogeneous integer solutions, and - - • a set F defining the sublattice of Zn the solution set lives in. -1.2. Brief tutorial 8 - - -Any solution z of the linear system can now be written as - X X - z =i+ αj hj + βk f k (1.2) - -for some i ∈ I and with hj ∈ H, fj ∈ F , and αj ∈ Z+ . - -Sign file. Let us finally clarify what the sign file PROJECT.sign is good for. The -sign file may declare a variable to be non-negative (1), to be non-positive (−1), or -to consider both cases independently and unite the answers (2). If a nonzero sign -has been assigned to a variable, the explicit representations (1.1) and (1.2) above -of a solution z have to respect the sign on that variable. The default setting for -each variable is 0 (when using qsolve and zsolve), that is, the sign need not be -respected in the explicit representation. In our example above, the first variable -is declared to be non-negative, the second and the third one expand to 2 · 2 = 4 -orthant constraints, and the fourth variable is unconstrained. Note, however, that -4ti2 does not decompose the problem internally into the four problems with sign -patterns (1, 1, 1, 0), (1, 1, −1, 0), (1, −1, 1, 0), and (1, −1, −1, 0), but deals with them -more efficiently at the same time. - - - - -1.2 Brief tutorial - -1.2.1 Solving linear systems over Z with zsolve - -In this example you learn about the function zsolve. - -Let us have a look at the linear system - - - x − y ≤ 2 - −3x + y ≤ 1 - x + y ≥ 1 - y ≥ 0 - -over Z. We have to create the files encoding the linear system. Let us call our project -system. Then the input files look as follows: -Chapter 1. Beginner’s guide 9 - - - system.mat system.rel system.rhs system.sign - 3 2 1 3 1 3 1 2 - 1 −1 < < > 2 1 1 0 1 - −3 1 - 1 1 -Then we call - - ./zsolve system - -This call creates two files - system.zinhom system.zhom - 4 2 3 2 - 0 1 1 1 - 2 0 1 2 - 1 0 1 3 - 1 1 -which correspond to the explicit description of all integer solutions: - Feasible solutions Computed representation - y = 3x + 1 y = 3x + 1 - 0000000000000 - 1111111111111 - 0000000000000 - 1111111111111 - 1111111111111 - 0000000000000 - 1111111111111 - 0000000000000 - 0000000000000 - 1111111111111 - 7 111111111111111111111111111 - 111111111111111111111111111 - 000000000000000000000000000 7 1111111111111 - 0000000000000 - 1111111111111 - 0000000000000 - 000000000000000000000000000 - 111111111111111111111111111 1111111111111 - 0000000000000 - 0000000000000 - 1111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 0000000000000 - 1111111111111 - 1111111111111 - 0000000000000 - 111111111111111111111111111 - 000000000000000000000000000 1111111111111 - 0000000000000 - 0000000000000 - 1111111111111 - 111111111111111111111111111 - 000000000000000000000000000 0000000000000 - 1111111111111 - 111111111111111111111111111 - 000000000000000000000000000 1111111111111 - 0000000000000 - 0000000000000 - 1111111111111 - 6 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 6 1111111111111 - 0000000000000 - 1111111111111 - 0000000000000 - 111111111111111111111111111 - 000000000000000000000000000 0000000000000 - 1111111111111 - 111111111111111111111111111 - 000000000000000000000000000 0000000000000 - 1111111111111 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 5 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 5 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 4 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - y=x-2 4 y=x-2 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 3 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 3 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 2 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 2 - 000000000000000000000000000 - 111111111111111111111111111 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 1 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 1 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 111111111111111111111111111 - 000000000000000000000000000 - 111111111111111111111111111 - 000000000000000000000000000 - 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 - - - -               - 1 2 0 1 1 1 1 - , , , + monoid , , . - 0 0 1 1 1 2 3 -Note that in the pictures above, we are only interested in the lattice points inside -the colored regions! The full regions are colored only for the purpose of visualizing -the covering of all feasible integer solutions by finitely many shifted copies of the -monoid       - 1 1 1 - monoid , , . - 1 2 3 -1.2. Brief tutorial 10 - - -1.2.2 Solving linear systems over Q with qsolve - -qsolve solves linear systems over Q; however, note that it only supports homoge- -neous linear systems, that is, systems with b = 0. - - - ./qsolve system - - -This call creates files - - system.qhom system.qfree - -To solve an inhomogeneous system Ax = b, x ≥ 0, you (still) need to do some work -yourself: - - - 1. Solve system Ax − bu = 0, x ≥ 0, u ≥ 0 using qsolve. - - 2. Keep those solutions with u = 0. (These generate the recession cone (of un- - bounded directions). - - 3. Normalize those solutions with u > 0 to have u = 1 (by dividing the vector - by u). Be aware that this could create rational numbers. - - 4. Drop the u-component. - - -Any solution to Ax = b, x ≥ 0 can then be obtained by adding one solution from 3. -to a nonnegative linear combination of solutions from 2. - - -1.2.3 Computing extreme rays and Hilbert bases - -In this example you learn about the functions rays and hilbert. (They are conve- -nient versions of qsolve and zsolve for particular cases.) -Let us consider the set of magic 3 × 3 squares with non-negative real entries, that -is, the set of all 3 × 3 arrays with non-negative real entries whose row sums, column -sums, and main diagonal sums all add up to the same number, the magic constant -of the square. -Chapter 1. Beginner’s guide 11 - - - - -Clearly, addition of two magic squares gives another magic square, as well as does -multiplication of a magic square by a non-negative number. Therefore, we may talk -about the cone of magic 3 × 3 squares. In fact, this cone is a pointed rational -polyhedral cone described by the linear system - - x11 + x12 + x13 = x21 + x22 + x23 - = x31 + x32 + x33 - = x11 + x21 + x31 - = x12 + x22 + x32 - = x13 + x23 + x33 - = x11 + x22 + x33 - = x31 + x22 + x13 - xij ≥ 0, for all i, j = 1, 2, 3. - -Bringing all xij to the left-hand side of these equations, the matrix A3×3 defining -this linear system is -   - 1 1 1 −1 −1 −1 0 0 0 - 0 −1 −1 −1  -   -  1 1 1 0 0 -   -  0 1 1 −1 0 0 −1 0 0  -   - A3×3 =  1 0 1 0 −1 0 0 −1 0 . -   -   -  1 1 0 -  0 0 −1 0 0 −1   -  0 1 1 -  0 −1 0 0 0 −1   - 1 1 0 0 −1 0 −1 0 0 - -Below, we will deal with the more interesting case of integer magic squares. For the -moment, however, we wish to compute the extreme rays of the magic square cone -{z : A3×3 z = 0, z ≥ 0}. -In order to call the function rays, we only have to create one file, say magic3x3.mat, -in which we specify the problem matrix A3×3 . The remaining data is set by default to -1.2. Brief tutorial 12 - - -”equations only”, to ”homogeneous system”, and to ”all variables are non-negative”. -Note that we are allowed to change these defaults (except homogeneity) by specifying -data in magic3x3.rel and magic3x3.sign - - magic3x3.mat - 7 9 - 1 1 1 −1 −1 −1 0 0 0 - 1 1 1 0 0 0 −1 −1 −1 - 0 1 1 −1 0 0 −1 0 0 - 1 0 1 0 −1 0 0 −1 0 - 1 1 0 0 0 −1 0 0 −1 - 0 1 1 0 −1 0 0 0 −1 - 1 1 0 0 −1 0 −1 0 0 - -Now we call - - ./rays magic3x3 - -which creates the single file - - magic3x3.ray - 4 9 - 0 2 1 2 1 0 1 0 2 - 1 2 0 0 1 2 2 0 1 - 2 0 1 0 1 2 1 2 0 - 1 0 2 2 1 0 0 2 1 - -that corresponds to the four extremal rays of the 3 × 3 magic square cone: - 0 2 1 1 2 0 2 0 1 1 0 2 - 2 1 0 0 1 2 0 1 2 2 1 0 - 1 0 2 2 0 1 1 2 0 0 2 1 - -Every magic 3 × 3 square is a non-negative linear combination of these four magic -squares. -If we turn now to integer magic squares, we are looking for a Hilbert basis of the -3 × 3 magic square cone. As the default settings for hilbert are the same as for -rays, we can use the same input file -Chapter 1. Beginner’s guide 13 - - - magic3x3.mat - 7 9 - 1 1 1 −1 −1 −1 0 0 0 - 1 1 1 0 0 0 −1 −1 −1 - 0 1 1 −1 0 0 −1 0 0 - 1 0 1 0 −1 0 0 −1 0 - 1 1 0 0 0 −1 0 0 −1 - 0 1 1 0 −1 0 0 0 −1 - 1 1 0 0 −1 0 −1 0 0 - -for this computation. However, to compute the Hilbert basis, we call - - ./hilbert magic3x3 - -which creates the single output file - - magic3x3.hil - 5 9 - 0 2 1 2 1 0 1 0 2 - 1 2 0 0 1 2 2 0 1 - 2 0 1 0 1 2 1 2 0 - 1 0 2 2 1 0 0 2 1 - 1 1 1 1 1 1 1 1 1 - -that corresponds to the five elements in the minimal Hilbert basis of the 3 × 3 magic -square cone: - - 0 2 1 1 2 0 2 0 1 1 0 2 - 2 1 0 0 1 2 0 1 2 2 1 0 - 1 0 2 2 0 1 1 2 0 0 2 1 - - - 1 1 1 - 1 1 1 - 1 1 1 -1.2. Brief tutorial 14 - - -Every integer magic 3 × 3 square is a non-negative integer linear combination of -these five integer magic squares. Note that the all-1 square is in the interior of the -magic square cone. -See [2, section 3.8] or [6] for details on the algorithm implemented. - - -1.2.4 Computing circuits and Graver bases - -In this example you learn about the functions graver, ppi, and circuits. -As an example of a Graver basis computation, let us compute the primitive partition -identities of order n = 4. Before we do the simple computation, let us explain what -a primitive partition identity is. -A partition identity is any identity of the form - - a1 + . . . + ak = b1 + . . . + bl - -with (generally not distinct) integer numbers 0 < ai , bj ≤ n. A partition identity is -called primitive if no proper subidentity exists. -For example, - 1+2+3=2+2+2 -is a partition identity which is not primitive, since it contains the subidentity - - 1+3=2+2 - -which is in fact primitive. -The description of the primitive partition identities for fixed n, however, is exactly -the description of the Graver basis of the matrix -   - An = 1 2 3 . . . n . - -Let us finally do the computation for n = 3. We create an input file ppi3 for 4ti2 -which looks as follows: - - ppi3.mat - 1 3 - 1 2 3 -Chapter 1. Beginner’s guide 15 - - -and call - - ./graver ppi3 - -This call will create an output file ppi3.gra that looks like: - - ppi3.gra - 5 3 - 3 0 −1 - 2 −1 0 - 0 3 −2 - 1 1 −1 - 1 −2 1 - -Thus, there are 5 primitive partition identities of order n = 3: - - 1+1+1 = 3 - 1+1 = 2 - 2+2+2 = 3+3 - 1+2 = 3 - 1+3 = 2+2 - -You may try and compute the primitive partition identities for bigger n, say n = 17, -20, or 23. Be aware, especially the latter two problems take a long, long time. What -is the biggest n for which you can compute the primitive partition identities of order -n on your machine within one hour? -Due to the very special structure of the matrix, there are algorithmic speed-ups -[4, 10, 13]. The currently fastest algorithm to compute primitive partition identities -is implemented in the function ppi of 4ti2. Try running - - ./ppi 17 - -which creates two files ppi17.mat (so we do not really have to create this file our- -selves) and the file ppi17.gra containing the desired identities. Compare this run- -ning time with the time taken by -1.2. Brief tutorial 16 - - - ./graver ppi17 - -Do you notice the speed-up? -Let us now turn to the question of determining the support-minimal partition iden- -tities. This, in fact, is the question of computing the circuits of the matrix -   - An = 1 2 3 . . . n . - -We use the same input file - - ppi3.mat - 1 3 - 1 2 3 - -as above and call - - ./circuits ppi3 - -This call will create an output file ppi3.cir that looks like: - - ppi3.cir - 3 3 - 3 0 −1 - 2 −1 0 - 0 3 −2 - -Thus, there are 3 support-minimal partition identities of order n = 3: - - 1+1+1 = 3 - 1+1 = 2 - 2+2+2 = 3+3 - - - -Note that support-minimal partition identities are primitive, since the circuits of a -matrix are contained in the Graver basis of this matrix. -See the book [2, section 3.8], or Hemmecke [7] for details on the algorithm imple- -mented. -Chapter 1. Beginner’s guide 17 - - -1.2.5 Integer programming and toric Gröbner bases - -In this example you learn about the functions minimize, groebner, and normalform. -The following neat example is based on the example presented in [12]. Let us assume -that we want to give change worth 99 cents using only pennies (1ct), nickels (5ct), -dimes (10ct), and quarters (25ct). Clearly, - - 4 · 1 + 4 · 5 + 0 · 10 + 3 · 25 = 99 - -would be one way to do it. Is this there another choice of 11 coins that sums up to -99ct but uses fewer nickels and quarters (in total)? In other words, we would like to -solve - -min{x2 + x4 : x1 + x2 + x3 + x4 = 11, x1 + 5x2 + 10x3 + 25x4 = 99, x1 , x2 , x3 , x4 ∈ Z+ } - -Let us set up the problem in 4ti2. - - 4coins.mat 4coins.zsol 4coins.sign 4coins.cost - 2 4 1 4 1 4 1 4 - 1 1 1 1 4 4 0 3 1 1 1 1 0 1 0 1 - 1 5 10 25 - -Note that we do not have to specify a relations file 4coins.rel, since already by -default all relations are assumed to be equations. Now we simply call - - ./minimize 4coins - -which creates the single output file - - 4coins.min - 1 4 - 4 1 4 2 - -From this, we conclude that - - 4 · 1 + 1 · 5 + 4 · 10 + 2 · 25 = 99 - -is an optimal choice, using only 3 instead of 7 nickels and quarters. -1.2. Brief tutorial 18 - - -Remark. Earlier versions of 4ti2 allowed to specify the right-hand side vector in -a file called 4coins.rhs, instead of giving a solution in 4coins.zsol. This is no -longer supported.  - -Since we already know a feasible solution, there is another way we might attack this -problem, namely via toric Gröbner bases. (See [2, Chapter 11] for an introduction to -toric ideals and their Gröbner bases, and also their generalizations, lattice ideals.) -For this, we first need to specify the matrix A and the cost vector c in the two files -4coins.mat and 4coins.cost: - - 4coins.mat 4coins.cost - 2 4 1 4 - 1 1 1 1 0 1 0 1 - 1 5 10 25 - -Then we compute the Gröbner basis of the toric ideal - - IA = hxu − xv : Au = Av, u, v ∈ Z4+ i - -with respect to a term ordering ≺ compatible with c, that is, c| v < c| u implies -xv ≺ xu . This toric Gröbner basis is computed by - - ./groebner 4coins - -and gives the output file - - 4coins.gro - -Remark. Many algorithm options are available and can be selected by command- -line options of groebner, see section 3.5. As reference to the algorithms we recom- -mend the book [2, section 11.4] or Hemmecke and Malkin [8], as well as Bigatti, -LaScala, and Robbiano [1], Gebauer and Möller [3], and Hoşten and Sturmfels [9]. -Since runnning times of the various algorithms are hard to predict, it may for some -hard problems make sense to start several computations in parallel, each with dif- -ferent algorithms.  - - -Then we specify our feasible solution in -Chapter 1. Beginner’s guide 19 - - - 4coins.feas - 1 4 - 4 4 0 3 - -and call - - ./normalform 4coins - -to produce the file - - 4coins.nf - 1 4 - 4 1 4 2 - -that also contains the desired optimal solution. -Remark. We could also specify a list of feasible solutions in 4coins.feas. Then -the call - - ./normalform 4coins - -creates a file 4coins.nf containing the minima to the corresponding integer pro- -grams. (If z0 is a feasible solution, the corresponding integer program is defined by -putting the right-hand side to Az0 .)  - - - -1.2.6 Markov Bases in Statistics - -In this example you learn about the functions markov and genmodel. -Let us consider the following 4 × 4 table of non-negative integer numbers together -with all row and column sums. -   - 11 23 34 3 71 -  4 15 12 11  42 -   -   -  17 2 3 25  47 - 16 12 22 7 57 - 48 52 71 46 -1.2. Brief tutorial 20 - - -In statistics, one wishes to sample among arrays that have fixed counts, say fixed row -and column sums. In order to sample, one needs a set of moves that, in particular, -do not change the counts when added to the current table. Clearly, these moves -must have counts 0 and thus quite naturally lead us to the toric ideal - - IA = hxu − xv : Au = Av, u, v ∈ Z16 - + i, - -where   - 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 -  0 0 0 0 1 1 1 1 0 0 0 0 0 0 0 0  -   -   -  0 0 0 0 0 0 0 0 1 1 1 1 0 0 0 0  -   -  0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1  - A= . -   -  1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0  -   -  0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0  -   -  0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0  -   - - 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 -It turns out that for any set of fixed counts, a (minimal) Markov basis is given by -a minimal generating set of this toric ideal. Note that a Markov basis connects all -non-negative tables with these counts in the sense that for any two non-negative -tables T1 and T2 with these counts, there is a sequence of non-negative tables T1 = -S0 , . . . , SN = T2 with the same counts as T1 and T2 and such that Si − Si−1 or -Si−1 − Si is in the Markov basis for i = 1, . . . , N . -For two-way tables the situation is still very simple as our computations with 4 × 4 -tables will now demonstrate. Write the matrix that defines our toric ideal in the file -4x4.mat: - - 4x4.mat - 8 16 - 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 - 0 0 0 0 1 1 1 1 0 0 0 0 0 0 0 0 - 0 0 0 0 0 0 0 0 1 1 1 1 0 0 0 0 - 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 - 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 - 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 - 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 0 - 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 -Chapter 1. Beginner’s guide 21 - - -Let us compute the Markov basis via the call - - ./markov 4x4 - -which creates a single output file 4x4.mar containing the 36 Markov basis elements. -Up to symmetry (swapping rows or columns), the Markov basis consists of the single -move   - 1 −1 0 0 -  −1 1 0 0  - . -   -  -  0 0 0 0  - 0 0 0 0 -In fact, this elementary move is (up to symmetry) the only representative of the -minimal Markov moves for arbitrary m × n tables using row and column counts. -Creating the matrices for statistical models may be pretty cumbersome. 4ti2 pro- -vides a litte function, genmodel, that helps the user with creating matrices for -hierarchical models defined by a complex. -The m × n tables problem above corresponds to the complex {{1}, {2}} on two -nodes with levels m and n, respectively. Let us encode the complex for 3 × 6 tables -with 1-marginals (row and column sums) in 3x6.mod. - - 3x6.mod - 3 - 3 6 - 2 - 1 1 - 1 2 - -and call - - ./genmodel 3x6 - -to produce the desired matrix file 3x6.mat. -The encoding of the complex should be obvious from the example: first we state the -number of nodes and their levels, then we give the number of maximal faces. Finally, -1.2. Brief tutorial 22 - - -we list each maximal face by first specifying the number of nodes on it and then by -listing these nodes. -Thus, a 3 × 4 × 6 table with 2-marginals (that is, again only counts along coordinate -axes) corresponds to the complex {{(1, 2)}, {(2, 3)}, {(3, 1)}} on 3 nodes with levels -3, 4, and 6, respectively. Thus, its encoding is in 4ti2 would look like: - - 3x4x6.mod - 3 - 3 4 6 - 3 - 2 1 2 - 2 2 3 - 2 3 1 - -A binary model on the bipartite graph K2,3 then reads as - - k2 3.mod - 5 - 2 2 2 2 2 - 6 - 2 1 3 - 2 1 4 - 2 1 5 - 2 2 3 - 2 2 4 - 2 2 5 -Chapter 2 - -Advanced guide - -In this part, we deal with several more advanced problem specifications in 4ti2. -First we introduce affine systems and their encodings. In fact, affine systems are -the basic objects used in 4ti2, since every linear system is transformed into an -affine system. However, in the integer situation, it is not always possible to trans- -form an affine system back into a linear system without adding variables or modulo -constraints. - - - -2.1 Affine systems and their encodings - -Let a + LZ be an “integer linear affine space” given by the vector a ∈ Zn and -by generators for the lattice LZ ⊆ Zn . We wish to find a finite sign-compatible -description for the set of all (integer) vectors x ∈ a + LZ . -As an example, let consider the linear space LR and the lattice LZ both spanned -by the two vectors (1, −2, 1, 0) and (2, −3, −0, 1). Moreover, consider the sign- -constraints (1, 2, 2, 0). Thus, we are looking for a finite explicit sign-compatible -description for all x that can be written as -   - 1 2 -  −2 −3  - x=  λ, -   -  1 0  - 0 1 - - 23 -2.1. Affine systems and their encodings 24 - - -with λ ∈ R2 and λ ∈ Z2 , respectively. -In order to solve this affine system using zsolve, we create the following input files -to encode the affine system: - - affine.lat affine.sign - 1 4 - 2 4 - 1 2 2 0 - 1 −1 1 0 - 2 −3 0 1 - - -and then call - - ./zsolve affine - -This creates the files affine.zhom and affine.zinhom. -Chapter 3 - -Command-line reference - -3.1 circuits -Usage: circuits [options] PROJECT - -Computes the circuits of a cone. - -Input Files: - PROJECT.mat A matrix (compulsory). - PROJECT.sign The sign constraints of the variables (’1’ means - non-negative, ’0’ means a free variable, and ’2’ means - both non-negative and non-positive). - It is optional, and the default is both. - PROJECT.rel The relations on the matrix rows (’<’,’>’,’=’). - It is optional and the default is all ’=’. - The mat must be given with this file. -Output Files: - PROJECT.cir The circuits of the cone. - PROJECT.qfree A basis for the linear subspace of the cone. - If this file does not exist then the linear subspace - is trivial. - -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - - 25 -3.1. circuits 26 - - - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -m, --mat Use the Matrix algorithm (default for 32 and 64). - -s, --support Use the Support algorithm (default for arbitrary). - -o, --order=ORDERING Set ORDERING as the ordering in which the columns - are chosen. The possible orderings are ‘maxinter’, - ‘minindex’, ‘maxcutoff’ (default), and ‘mincutoff’. - -f, --output-freq=n Set the frequency of output (default is 1000). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -Chapter 3. Command-line reference 27 - - -3.2 genmodel - -usage: genmodel [--options] FILENAME - -Computes the problem matrix corresponding to graphical statistical models -given by a simplicial complex and levels on the nodes. - -Options: - -q, --quiet No output is written to the screen - -Input file: -FILENAME.mod Simplicial complex and levels on the nodes - -Output file: -FILENAME.mat Matrix file - -Example: Consider the problem of 3x3x3 tables with 2-marginals. These -are given by K_3 as the simplicial complex on 3 nodes and with levels -of 3 on each node. In ’333.mod’ write: -3 -3 3 3 -3 -2 1 2 -2 2 3 -2 3 1 -Calling ’genmodel 333’ produces the following file ’333.mat’: -27 27 -1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 -0 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 -[...] -1 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -0 1 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -0 0 1 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -[...] -1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -3.2. genmodel 28 - - -[...] -Chapter 3. Command-line reference 29 - - -3.3 gensymm -usage: gensymm [--options] A B C D FILENAME - -Computes the generators for the symmetry group acting on 4-way tables -with 3-marginals. By putting one side length to 1, this includes -3-way tables with 2-marginals. - -Options: - -q, --quiet No output is written to the screen - -Output file: - FILENAME.sym generators for the symmetry group - -Example: Consider the problem of 3x3x3 tables with 2-marginals. Calling - gensymm 3 3 3 1 333 -produces the file ’333.sym’ containing the following lines. - -9 27 -10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 1 2 3 4 5 6 7 8 9 -10 11 12 13 14 15 16 17 18 1 2 3 4 5 6 7 8 9 19 20 21 22 23 24 25 26 27 -4 5 6 7 8 9 1 2 3 13 14 15 16 17 18 10 11 12 22 23 24 25 26 27 19 20 21 -4 5 6 1 2 3 7 8 9 13 14 15 10 11 12 16 17 18 22 23 24 19 20 21 25 26 27 -2 3 1 5 6 4 8 9 7 11 12 10 14 15 13 17 18 16 20 21 19 23 24 22 26 27 25 -2 1 3 5 4 6 8 7 9 11 10 12 14 13 15 17 16 18 20 19 21 23 22 24 26 25 27 -1 2 3 10 11 12 19 20 21 4 5 6 13 14 15 22 23 24 7 8 9 16 17 18 25 26 27 -1 10 19 4 13 22 7 16 25 2 11 20 5 14 23 8 17 26 3 12 21 6 15 24 9 18 27 -1 4 7 2 5 8 3 6 9 10 13 16 11 14 17 12 15 18 19 22 25 20 23 26 21 24 27 -3.4. graver 30 - - -3.4 graver - -Usage: graver [options] PROJECT - -Computes the Graver basis of a matrix or a given lattice. - -Basic options: - -p PREC, --precision=PREC Use precision (32, 64, gmp). Default is 32 bit - -m, --maxnorm Write vectors with maximum norm to PROJECT.maxnorm - -b [FREQ], --backup[=FREQ] Frequently backup status to PROJECT.backup - -r, --resume Resume from backup file PROJECT.backup - -h, --help Display this help - --version Display version information - -Output options: - -q, --quiet Quiet mode - -u, --update[=1] Updated output on console (default) - -uu, --update=2 More verbose updated output on console - -v, --verbose[=1] Output once every variable computation - -vv, --verbose=2 Output once every norm sum computation - -vvv, --verbose=3 Output once every norm computation - -Logging options: - -n, --log=0 Disable logging (default) - -l, --log[=1] Log once every variable computation to PROJECT.log - -ll, --log=2 Log once every norm sum computation to PROJECT.log - -lll, --log=3 Log once every norm computation to PROJECT.log - -Input files: -PROJECT.mat Matrix -PROJECT.lat Lattice basis (can be provided instead of matrix) -PROJECT.sign Sign of columns (optional) -PROJECT.lb Lower bounds of columns (optional) -PROJECT.ub Upper bounds of columns (optional) - -Backup files: -Chapter 3. Command-line reference 31 - - -PROJECT.backup Backup file -PROJECT.backup~ Temporary backup file - (if it exists, it may be newer than PROJECT.backup) - -Output files: -PROJECT.gra Graver basis -PROJECT.zfree Free part of the solution -PROJECT.maxnorm Vectors with maximum norm (if -m, --maxnorm is in use) -3.5. groebner 32 - - -3.5 groebner - -Usage: groebner [options] PROJECT - -Computes a Groebner basis of the toric ideal of a matrix, -or, more general, of the lattice ideal of a lattice. - -Input Files: - PROJECT.mat A matrix (optional if lattice basis is given). - PROJECT.lat A lattice basis (optional if matrix is given). - PROJECT.cost The cost matrix, which determines the term ordering - (optional, default is degrevlex). - Ties are broken with degrevlex. - PROJECT.sign The sign constraints of the variables (’1’ means - non-negative and ’0’ means a free variable). - It is optional, and the default is all non-negative. - PROJECT.mar The Markov basis/generating set of the lattice (optional). - PROJECT.weights The weight vectors used for truncation (optional). - PROJECT.weights.max The maximum weights used for truncation. - This file is needed when PROJECT.weights exists. - PROJECT.zsol An integer solution to specify a fiber (optional). - The integer solution is used for truncation. -Output Files: - PROJECT.gro The Groebner basis of the lattice. - -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -a, --algorithm=ALG Select ALG as the completion procedure for - computing Groebner bases. ALG is one of - ‘fifo’, ‘weighted’, or ’unbounded.’ - -g, --generation=ALG Select ALG as the procedure for computing - a generating set or Markov basis. ALG is - one of ‘hybrid’ (default), ‘project-and-lift’, - ‘max-min’, or ’saturation’. -Chapter 3. Command-line reference 33 - - - -t, --truncation=TRUNC Set TRUNC as the truncation method. TRUNC is - of the following: ‘ip’, ‘lp’, ‘weight’ (default), - or ‘none’. Only relevant if ‘zsol’ is given. - -m, --minimal=STATE If STATE is ‘yes’ (default), then 4ti2 will - compute a minimal Markov basis. If STATE is - ’no’, then the Markov basis will not - necessarily be minimal. - -r, --auto-reduce-freq=n Set the frequency of auto reduction. - (default is 2500). - -f, --output-freq=n Set the frequency of output (default is 1000). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -3.6. hilbert 34 - - -3.6 hilbert - -Usage: hilbert [options] PROJECT - -Computes the Hilbert basis of a matrix or a given lattice. - -Basic options: - -p PREC, --precision=PREC Use precision (32, 64, gmp). Default is 32 bit - -m, --maxnorm Write vectors with maximum norm to PROJECT.maxnorm - -b [FREQ], --backup[=FREQ] Frequently backup status to PROJECT.backup - -r, --resume Resume from backup file PROJECT.backup - -h, --help Display this help - --version Display version information - -Output options: - -q, --quiet Quiet mode - -u, --update[=1] Updated output on console (default) - -uu, --update=2 More verbose updated output on console - -v, --verbose[=1] Output once every variable computation - -vv, --verbose=2 Output once every norm sum computation - -vvv, --verbose=3 Output once every norm computation - -Logging options: - -n, --log=0 Disable logging (default) - -l, --log[=1] Log once every variable computation to PROJECT.log - -ll, --log=2 Log once every norm sum computation to PROJECT.log - -lll, --log=3 Log once every norm computation to PROJECT.log - -Input files: -PROJECT.mat Matrix -PROJECT.lat Lattice basis (can be provided instead of matrix) -PROJECT.rel Relations (<, >, =) -PROJECT.sign Sign of columns (optional) -PROJECT.ub Upper bounds of columns (optional) - -Backup files: -Chapter 3. Command-line reference 35 - - -PROJECT.backup Backup file -PROJECT.backup~ Temporary backup file - (if it exists, it may be newer than PROJECT.backup) - -Output files: -PROJECT.hil Hilbert basis -PROJECT.zfree Free part of the solution -PROJECT.maxnorm Vectors with maximum norm (if -m, --maxnorm is in use) -3.7. markov 36 - - -3.7 markov - -Usage: markov [options] PROJECT - -Computes a Markov basis (generating set) of the toric ideal -of a matrix or, more general, of the lattice ideal of a lattice. - -Input Files: - PROJECT A matrix (optional only if lattice basis is given). - PROJECT.lat A lattice basis (optional only if matrix is given). - PROJECT.sign The sign constraints of the variables (’1’ means - non-negative and ’0’ means a free variable). - It is optional, and the default is all non-negative. - PROJECT.weights The weight vectors used for truncation (optional). - PROJECT.weights.max The maximum weights used for truncation. - This file is needed when PROJECT.weights exists. - PROJECT.zsol An integer solution to specify a fiber (optional). - The integer solution is used for truncation. -Output Files: - PROJECT.mar The Markov basis/generating set of the lattice. -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -a, --algorithm=ALG Select ALG as the completion procedure for - computing Groebner bases. ALG is one of - ‘fifo’, ‘weighted’, or ’unbounded.’ - -g, --generation=ALG Select ALG as the procedure for computing - a generating set or Markov basis. ALG is - one of ‘hybrid’ (default), ‘project-and-lift’, - ‘max-min’, or ’saturation’. - -t, --truncation=TRUNC Set TRUNC as the truncation method. TRUNC is - of the following: ‘ip’, ‘lp’, ‘weight’ (default), - or ‘none’. Only relevant if ‘zsol’ is given. - -m, --minimal=STATE If STATE is ‘yes’ (default), then 4ti2 will - compute a minimal Markov basis. If STATE is -Chapter 3. Command-line reference 37 - - - ’no’, then the Markov basis will not - necessarily be minimal. - -r, --auto-reduce-freq=n Set the frequency of auto reduction. - (default is 2500). - -f, --output-freq=n Set the frequency of output (default is 1000). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -3.8. minimize 38 - - -3.8 minimize -Usage: minimize [options] PROJECT - -Computes the minimal solution of an integer linear program -or, more general, a lattice program, using a Groebner basis. - -Input Files: - PROJECT.mat A matrix (optional only if lattice basis is given). - PROJECT.lat A lattice basis (optional only if matrix is given). - PROJECT.cost The cost vector. Exactly one vector allowed. - PROJECT.zsol An integer solution to specify a fiber (needed). - PROJECT.sign The sign constraints of the variables (’1’ means - non-negative and ’0’ means a free variable). - It is optional, and the default is all non-negative. -Output Files: - PROJECT.min The minimal solution for the given fiber. - -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -a, --algorithm=ALG Select ALG as the completion procedure for - computing Groebner bases. ALG is one of - ‘fifo’, ‘weighted’, or ’unbounded.’ - -t, --truncation=TRUNC Set TRUNC as the truncation method. TRUNC is - of the following: ‘ip’, ‘lp’, ‘weight’ (default), - or ‘none’. Only relevant if ‘zsol’ is given. - -r, --auto-reduce-freq=n Set the frequency of auto reduction. - (default is 2500). - -f, --output-freq=n Set the frequency of output (default is 1000). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -Chapter 3. Command-line reference 39 - - -3.9 normalform -Usage: normalform [options] PROJECT - -Computes the normal form of a list of feasible points. - -Input Files: - PROJECT.mat A matrix (optional if lattice basis is given). - PROJECT.lat A lattice basis (optional if matrix is given). - PROJECT.gro The Groebner basis of the lattice (needed). - PROJECT.cost The cost matrix (optional, default is degrevlex). - Ties are broken with degrevlex. - PROJECT.feas An list of integer feasible solutions (needed). - PROJECT.sign The sign constraints of the variables (’1’ means - non-negative and ’0’ means a free variable). - It is optional, and the default is all non-negative. -Output Files: - PROJECT.nf The normal forms of the feasible solutions. - -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -3.10. output 40 - - -3.10 output - -usage: output [--options] FILENAME.EXT - -Transforms a 4ti2 matrix file to something else. - -General options: - --quiet No output is written to the screen. - -Options that control what to output: their output files: - --binomials Write vectors as binomials. FILENAME.EXT.bin - Use an optional input file - ’FILENAME.EXT.vars’ - to specify variable names. - - --maple Write vectors as Maple list. FILENAME.EXT.maple - This format is suitable also for - CoCoA, Mathematica, Macaulay2. - - --0-1 Extract vectors with 0-1 - components only. FILENAME.EXT.0-1 - - --transpose Transpose matrix and write it FILENAME.EXT.tra - in 4ti2 format. - - --degree Print 1-norms of all vectors. - - --degree N Extract all vectors of 1-norm FILENAME.EXT.deg.N - equal to N. - - --degree N1 N2 Extract all vectors of 1-norm FILENAME.EXT.deg.N1-N2 - between N1 and N2 (inclusive). - - --support Print supports of all vectors. - - --support S Extract all vectors of support FILENAME.EXT.supp.S -Chapter 3. Command-line reference 41 - - - size equal to S. - - --support S1 S2 Extract all vectors of support FILENAME.EXT.supp.S1-S2 - size between S1 and S2 (incl.) - - --positive Extract positive parts of vectors. FILENAME.EXT.pos - Corresponds to leading terms of - binomials. - - --3way A B C Write vectors as 3-way tables FILENAME.EXT.3way - of size A x B x C. - - --nonzero-at K Extract all vectors that have FILENAME.EXT.nonzero.K - nonzero K-th coordinate. - -Undocumented or obscure options for experts: - --representatives - --dominated Extract all non-dominated vectors FILENAME.EXT.nondom - --maximal-non-dominated FILENAME.EXT.maxnondom - --expand-representatives-to-full-orbits - --type T - --AxB Computes a matrix-vector product. - --macaulay2 - --mathematica - --cocoa - --sum Print the sum of the columns. - --submatrix LISTFILENAME FILENAME.EXT.submat - --remove-column I FILENAME.EXT.remcol - --remcol I FILENAME.EXT.remcol - --stabilizer SYMMFILENAME FILENAME.EXT.stab - --fill-column FILENAME.EXT.fil - --add-column FILENAME.EXT.addcol - --fix I1 ... IK Extract fixed vectors, FILENAME.EXT.fix - that is, those vectors that - have x[i]=i for the given i. - --fox I1 ... IK Extract relaxed fixed vectors. FILENAME.EXT.fox -3.10. output 42 - - - --initial-forms Extract initial forms. FILENAME.ini - (Call with FILENAME rather FILENAME.ini.bin - than FILENAME.EXT. Reads - FILENAME.gro and - optionally FILENAME.cost and - FILENAME.vars. - -Examples: - ’output --binomials file.gra’ writes the Graver basis elements as - binomials in ’file.gra.bin’. - - ’output --0-1 foo.gra’ extracts the 0-1 elements from the Graver basis - elements and writes them into ’foo.gra.0-1’. -Chapter 3. Command-line reference 43 - - -3.11 ppi -usage: ppi [--binary-output] N - -Computes the primitive partition identities, that is, the Graver basis of [1 2 3 ... N]. - -Options: - -b, --binary-output Create a binary file ppiN.dat instead of text file ppiN.gra -3.12. qsolve 44 - - -3.12 qsolve -Usage: qsolve [options] PROJECT - -Computes a generator description of a cone. - -Input Files: - PROJECT.mat A matrix (compulsory). - PROJECT.sign The sign constraints of the variables (’1’ means - non-negative, ’0’ means a free variable, and ’2’ means - both non-negative and non-positive). - It is optional, and the default is all free. - PROJECT.rel The relations on the matrix rows (’<’,’>’,’=’). - It is optional and the default is all ’=’. - The mat must be given with this file. -Output Files: - PROJECT.qhom The homogeneous generators of the linear system. - PROJECT.qfree A basis for the linear subspace of the cone. - If this file does not exist then the linear subspace - is trivial. - -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -m, --mat Use the Matrix algorithm (default for 32 and 64). - -s, --support Use the Support algorithm (default for arbitrary). - -o, --order=ORDERING Set ORDERING as the ordering in which the columns - are chosen. The possible orderings are ‘maxinter’, - ‘minindex’, ‘maxcutoff’ (default), and ‘mincutoff’. - -f, --output-freq=n Set the frequency of output (default is 1000). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -Chapter 3. Command-line reference 45 - - -3.13 rays -Usage: rays [options] PROJECT - -Computes the extreme rays of a cone. - -Input Files: - PROJECT.mat A matrix (compulsory). - PROJECT.sign The sign constraints of the variables (’1’ means - non-negative, ’0’ means a free variable, and ’2’ means - both non-negative and non-positive). - It is optional, and the default is all non-negative. - PROJECT.rel The relations on the matrix rows (’<’,’>’,’=’). - It is optional and the default is all ’=’. - The mat must be given with this file. -Output Files: - PROJECT.ray The extreme rays of the cone. - PROJECT.qfree A basis for the linear subspace of the cone. - If this file does not exist then the linear subspace - is trivial. - -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -m, --mat Use the Matrix algorithm (default for 32 and 64). - -s, --support Use the Support algorithm (default for arbitrary). - -o, --order=ORDERING Set ORDERING as the ordering in which the columns - are chosen. The possible orderings are ‘maxinter’, - ‘minindex’, ‘maxcutoff’ (default), and ‘mincutoff’. - -f, --output-freq=n Set the frequency of output (default is 1000). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -3.14. walk 46 - - -3.14 walk -Usage: walk [options] PROJECT - -Computes the minimal solution of an integer linear program -or, more general, a lattice program using a Groebner basis. - -Input Files: - PROJECT.mat A matrix (optional only if lattice basis is given). - PROJECT.lat A lattice basis (optional only if matrix is given). - PROJECT.gro.start The starting Groebner basis (needed). - PROJECT.gro.cost The starting cost vector (optional, default is degrevlex). - Ties are broken with degrevlex. - PROJECT.cost The target cost vector (optional, default is degrevlex). - Ties are broken with degrevlex. - PROJECT.zsol An integer solution to specify a fiber (needed). - PROJECT.sign The sign constraints of the variables (’1’ means - non-negative and ’0’ means a free variable). - It is optional, and the default is all non-negative. -Output Files: - PROJECT.gro The Groebner basis of the lattice. - -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -t, --truncation=TRUNC Set TRUNC as the truncation method. TRUNC is - of the following: ‘ip’, ‘lp’, ‘weight’ (default), - or ‘none’. Only relevant if ‘zsol’ is given. - -f, --output-freq=n Set the frequency of output (default is 1000). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -Chapter 3. Command-line reference 47 - - -3.15 zbasis -Usage: zbasis [options] PROJECT - -Computes an integer lattice basis. - -Input Files: - PROJECT A matrix (needed). -Output Files: - PROJECT.lat A lattice basis. -Options: - -p, --precision=PREC Select PREC as the integer arithmetic precision. - PREC is one of the following: ‘64’ (default), - ‘32’, and ‘arbitrary’ (only ‘arb‘ is needed). - -q, --quiet Do not output anything to the screen. - -h, --help Display this help and exit. -3.16. zsolve 48 - - -3.16 zsolve - -Usage: zsolve [options] PROJECT - -Solves linear inequality and equation systems over the integers. - -Basic options: - -p PREC, --precision=PREC Use precision (32, 64, gmp). Default is 32 bit - -m, --maxnorm Write vectors with maximum norm to PROJECT.maxnorm - -b [FREQ], --backup[=FREQ] Frequently backup status to PROJECT.backup - -r, --resume Resume from backup file PROJECT.backup - -h, --help Display this help - --version Display version information - -Output options: - -q, --quiet Quiet mode - -u, --update[=1] Updated output on console (default) - -uu, --update=2 More verbose updated output on console - -v, --verbose[=1] Output once every variable computation - -vv, --verbose=2 Output once every norm sum computation - -vvv, --verbose=3 Output once every norm computation - -Logging options: - -n, --log=0 Disable logging (default) - -l, --log[=1] Log once every variable computation to PROJECT.log - -ll, --log=2 Log once every norm sum computation to PROJECT.log - -lll, --log=3 Log once every norm computation to PROJECT.log - -Input files: -PROJECT.mat Matrix -PROJECT.lat Lattice basis (can be provided instead of matrix) -PROJECT.rhs Right hand side -PROJECT.rel Relations (<, >, =) -PROJECT.sign Sign of columns (optional) -PROJECT.lb Lower bounds of columns (optional) -PROJECT.ub Upper bounds of columns (optional) -Chapter 3. Command-line reference 49 - - - - -Backup files: -PROJECT.backup Backup file -PROJECT.backup~ Temporary backup file - (if it exists, it may be newer than PROJECT.backup) - -Output files: -PROJECT.zinhom Inhomogeneous part of the solution diff --git a/apn/lean/docs/4ti2/LICENSE b/apn/lean/docs/4ti2/LICENSE deleted file mode 100644 index d511905c..00000000 --- a/apn/lean/docs/4ti2/LICENSE +++ /dev/null @@ -1,339 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. diff --git a/apn/lean/docs/csdp/LICENSE b/apn/lean/docs/csdp/LICENSE deleted file mode 100644 index 45977f0b..00000000 --- a/apn/lean/docs/csdp/LICENSE +++ /dev/null @@ -1,237 +0,0 @@ -Common Public License Version 1.0 - -THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS COMMON -PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF -THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. - -1. DEFINITIONS - -"Contribution" means: - - a) in the case of the initial Contributor, the initial code and - documentation distributed under this Agreement, and - - b) in the case of each subsequent Contributor: - - i) changes to the Program, and - - ii) additions to the Program; - - where such changes and/or additions to the Program originate from - and are distributed by that particular Contributor. A Contribution - 'originates' from a Contributor if it was added to the Program by - such Contributor itself or anyone acting on such Contributor's - behalf. Contributions do not include additions to the Program - which: (i) are separate modules of software distributed in - conjunction with the Program under their own license agreement, - and (ii) are not derivative works of the Program. - -"Contributor" means any person or entity that distributes the Program. - -"Licensed Patents " mean patent claims licensable by a Contributor -which are necessarily infringed by the use or sale of its Contribution -alone or when combined with the Program. - -"Program" means the Contributions distributed in accordance with this -Agreement. - -"Recipient" means anyone who receives the Program under this -Agreement, including all Contributors. - -2. GRANT OF RIGHTS - - a) Subject to the terms of this Agreement, each Contributor hereby - grants Recipient a non-exclusive, worldwide, royalty-free - copyright license to reproduce, prepare derivative works of, - publicly display, publicly perform, distribute and sublicense the - Contribution of such Contributor, if any, and such derivative - works, in source code and object code form. - - b) Subject to the terms of this Agreement, each Contributor hereby - grants Recipient a non-exclusive, worldwide, royalty-free patent - license under Licensed Patents to make, use, sell, offer to sell, - import and otherwise transfer the Contribution of such - Contributor, if any, in source code and object code form. This - patent license shall apply to the combination of the Contribution - and the Program if, at the time the Contribution is added by the - Contributor, such addition of the Contribution causes such - combination to be covered by the Licensed Patents. The patent - license shall not apply to any other combinations which include - the Contribution. No hardware per se is licensed hereunder. - - c) Recipient understands that although each Contributor grants the - licenses to its Contributions set forth herein, no assurances are - provided by any Contributor that the Program does not infringe the - patent or other intellectual property rights of any other entity. - Each Contributor disclaims any liability to Recipient for claims - brought by any other entity based on infringement of intellectual - property rights or otherwise. As a condition to exercising the - rights and licenses granted hereunder, each Recipient hereby - assumes sole responsibility to secure any other intellectual - property rights needed, if any. For example, if a third party - patent license is required to allow Recipient to distribute the - Program, it is Recipient's responsibility to acquire that license - before distributing the Program. - - d) Each Contributor represents that to its knowledge it has - sufficient copyright rights in its Contribution, if any, to grant - the copyright license set forth in this Agreement. - -3. REQUIREMENTS - -A Contributor may choose to distribute the Program in object code form -under its own license agreement, provided that: - - a) it complies with the terms and conditions of this Agreement; - and - - b) its license agreement: - - i) effectively disclaims on behalf of all Contributors all - warranties and conditions, express and implied, including - warranties or conditions of title and non-infringement, and - implied warranties or conditions of merchantability and fitness - for a particular purpose; - - ii) effectively excludes on behalf of all Contributors all - liability for damages, including direct, indirect, special, - incidental and consequential damages, such as lost profits; - - iii) states that any provisions which differ from this Agreement - are offered by that Contributor alone and not by any other party; - and - - iv) states that source code for the Program is available from such - Contributor, and informs licensees how to obtain it in a - reasonable manner on or through a medium customarily used for - software exchange. - -When the Program is made available in source code form: - - a) it must be made available under this Agreement; and - - b) a copy of this Agreement must be included with each copy of the - Program. - -Contributors may not remove or alter any copyright notices contained -within the Program. - -Each Contributor must identify itself as the originator of its -Contribution, if any, in a manner that reasonably allows subsequent -Recipients to identify the originator of the Contribution. - -4. COMMERCIAL DISTRIBUTION - -Commercial distributors of software may accept certain -responsibilities with respect to end users, business partners and the -like. While this license is intended to facilitate the commercial use -of the Program, the Contributor who includes the Program in a -commercial product offering should do so in a manner which does not -create potential liability for other Contributors. Therefore, if a -Contributor includes the Program in a commercial product offering, -such Contributor ("Commercial Contributor") hereby agrees to defend -and indemnify every other Contributor ("Indemnified Contributor") -against any losses, damages and costs (collectively "Losses") arising -from claims, lawsuits and other legal actions brought by a third party -against the Indemnified Contributor to the extent caused by the acts -or omissions of such Commercial Contributor in connection with its -distribution of the Program in a commercial product offering. The -obligations in this section do not apply to any claims or Losses -relating to any actual or alleged intellectual property -infringement. In order to qualify, an Indemnified Contributor must: a) -promptly notify the Commercial Contributor in writing of such claim, -and b) allow the Commercial Contributor to control, and cooperate with -the Commercial Contributor in, the defense and any related settlement -negotiations. The Indemnified Contributor may participate in any such -claim at its own expense. - -For example, a Contributor might include the Program in a commercial -product offering, Product X. That Contributor is then a Commercial -Contributor. If that Commercial Contributor then makes performance -claims, or offers warranties related to Product X, those performance -claims and warranties are such Commercial Contributor's responsibility -alone. Under this section, the Commercial Contributor would have to -defend claims against the other Contributors related to those -performance claims and warranties, and if a court requires any other -Contributor to pay any damages as a result, the Commercial Contributor -must pay those damages. - -5. NO WARRANTY - -EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS -PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY -WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY -OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely -responsible for determining the appropriateness of using and -distributing the Program and assumes all risks associated with its -exercise of rights under this Agreement, including but not limited to -the risks and costs of program errors, compliance with applicable -laws, damage to or loss of data, programs or equipment, and -unavailability or interruption of operations. - -6. DISCLAIMER OF LIABILITY - -EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR -ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING -WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR -DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED -HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -7. GENERAL - -If any provision of this Agreement is invalid or unenforceable under -applicable law, it shall not affect the validity or enforceability of -the remainder of the terms of this Agreement, and without further -action by the parties hereto, such provision shall be reformed to the -minimum extent necessary to make such provision valid and enforceable. - -If Recipient institutes patent litigation against a Contributor with -respect to a patent applicable to software (including a cross-claim or -counterclaim in a lawsuit), then any patent licenses granted by that -Contributor to such Recipient under this Agreement shall terminate as -of the date such litigation is filed. In addition, if Recipient -institutes patent litigation against any entity (including a -cross-claim or counterclaim in a lawsuit) alleging that the Program -itself (excluding combinations of the Program with other software or -hardware) infringes such Recipient's patent(s), then such Recipient's -rights granted under Section 2(b) shall terminate as of the date such -litigation is filed. - -All Recipient's rights under this Agreement shall terminate if it -fails to comply with any of the material terms or conditions of this -Agreement and does not cure such failure in a reasonable period of -time after becoming aware of such noncompliance. If all Recipient's -rights under this Agreement terminate, Recipient agrees to cease use -and distribution of the Program as soon as reasonably -practicable. However, Recipient's obligations under this Agreement and -any licenses granted by Recipient relating to the Program shall -continue and survive. - -Everyone is permitted to copy and distribute copies of this Agreement, -but in order to avoid inconsistency the Agreement is copyrighted and -may only be modified in the following manner. The Agreement Steward -reserves the right to publish new versions (including revisions) of -this Agreement from time to time. No one other than the Agreement -Steward has the right to modify this Agreement. IBM is the initial -Agreement Steward. IBM may assign the responsibility to serve as the -Agreement Steward to a suitable separate entity. Each new version of -the Agreement will be given a distinguishing version number. The -Program (including Contributions) may always be distributed subject to -the version of the Agreement under which it was received. In addition, -after a new version of the Agreement is published, Contributor may -elect to distribute the Program (including its Contributions) under -the new version. Except as expressly stated in Sections 2(a) and 2(b) -above, Recipient receives no rights or licenses to the intellectual -property of any Contributor under this Agreement, whether expressly, -by implication, estoppel or otherwise. All rights in the Program not -expressly granted under this Agreement are reserved. - -This Agreement is governed by the laws of the State of New York and -the intellectual property laws of the United States of America. No -party to this Agreement will bring a legal action under this Agreement -more than one year after the cause of action arose. Each party waives -its rights to a jury trial in any resulting litigation. diff --git a/apn/lean/docs/csdp/csdp-user-guide.txt b/apn/lean/docs/csdp/csdp-user-guide.txt deleted file mode 100644 index d5735eaf..00000000 --- a/apn/lean/docs/csdp/csdp-user-guide.txt +++ /dev/null @@ -1,335 +0,0 @@ - - - CSDP 6.2.0 User’s Guide - Brian Borchers - July 24, 2017 - - -Introduction -CSDP is a software package for solving semidefinite programming problems. The -algorithm is a predictor–corrector version of the primal–dual barrier method of -Helmberg, Rendl, Vanderbei, and Wolkowicz [4]. A more detailed, but now -somewhat outdated description of the algorithms in CSDP can be found in [1]. -CSDP is written in C for efficiency and portability. On systems with multiple -processors and shared memory, CSDP can run in parallel. CSDP uses OpenMP -directives in the C source code to tell the compiler how to parallelize various -loops. The parallel implementation is described in [2]. The code is designed -to make use of highly optimized linear algebra routines from the LAPACK and -BLAS libraries. - CSDP also has a number of features that make it flexible. CSDP can work -with general symmetric matrices or with matrices that have defined block di- -agonal structure. CSDP is designed to handle constraint matrices with general -sparse structure. The code takes advantage of this structure in efficiently con- -structing the system of equations that is solved at each iteration of the algo- -rithm. - In addition to its default termination criteria, CSDP includes a feature that -allows the user to terminate the solution process after any iteration. For exam- -ple, this feature has been used within a branch and bound code for maximum -independent set problems to terminate the bounding calculations as soon as a -bound has been obtained that is good enough to fathom the current note. The -library also contains routines for writing SDP problems and solutions to files -and reading problems and solutions from files. - A stand alone solver program is included for solving SDP problems that have -been written in the SDPA sparse format [3]. An interface to MATLAB and the -open source MATLAB clone Octave is also provided. This interface can be used -to solve problems that are in the format used by the SeDuMi [6]. - This document describes how to use the stand alone solver, MATLAB and -Octave interface, and library routines. For detailed instructions on how to -compile and install CSDP see the INSTALL file in the main directory. - - - - -The SDP Problem -CSDP solves semidefinite programming problems of the form - - max tr (CX) - A(X) = a (1) - X  0 - -where   - tr (A1 X) -  tr (A2 X)  - A(X) =  . (2) -  ...  - tr (Am X) -Here X  0 means that X is positive semidefinite. All of the matrices Ai , X, -and C are assumed to be real and symmetric. - The dual of this SDP is - min aT y - T - A (y) − C = Z (3) - Z  0 - -where - m - X - AT (y) = y i Ai . (4) - i=1 - - Other semidefinite programming packages use slight variations on this primal– -dual pair. For example, the primal–dual pair used in SDPA interchanges the -primal and dual problems. - Users of CSDP can specify their own termination criteria. However, the -default criteria are that - tr(XZ) < 1.0 × 10−8 - 1+|aT y|+|tr(CX)| - kA(x)−ak2 - 1+kak2 < 1.0 × 10−8 - T - (5) - kA (y)−C−ZkF - 1+kCkF < 1.0 × 10−8 - X, Z  0. - - Note that for feasible primal and dual solutions, aT y − tr(CX) = tr(XZ). -Thus the first of these criteria insures that the relative duality gap is small. In -practice, there are sometimes solutions which satisfy our primal and dual feasi- -bility tolerances but have duality gaps which are not close to tr(XZ). In some -cases, the duality gap may even become negative. Because of this ambiguity, we -use the tr(XZ) gap instead of the difference between the objective functions. -An option in the param.csdp file allows CSDP to use the difference of the primal -objective functions instead of the tr(XZ) gap. - The matrices X and Z are considered to be positive definite when their -Cholesky factorizations can be computed. In practice, this is somewhat more -conservative than simply requiring all eigenvalues to be nonnegative. - - - The Seventh DIMACS Implementation Challenge used a slightly different -set of error measures [5]. For convenience in benchmarking, CSDP includes -these DIMACS error measures in its output. - To test for primal infeasibility, CSDP checks the inequality - - −aT y - > 1.0 × 108 . (6) - kAT (y) − ZkF - -If CSDP detects that a problem is primal infeasible, then it will announce this -in its output and return a dual solution with aT y = −1, and kAT (y) − Zk very -small. This acts as a certificate of primal infeasibility. - Similarly, CSDP tests for dual infeasibility by checking - - tr(CX) - > 1.0 × 108 . (7) - kA(X)k2 - -If CSDP detects that a problem is dual infeasible, it announces this in its output -and returns a primal solution with tr(CX) = 1, and kA(X)k small. This acts -as a certificate of the dual infeasibility. - The tolerances for primal and dual feasibility and the relative duality gap -can be changed by editing CSDP’s parameter file. See the following section on -using the stand alone solver for a description of this parameter file. - - -Using the stand alone solver -CSDP includes a program which can be used to solve SDP’s that have been -written in the SDPA sparse format. Usage is - csdp [] [] - -where is the name of a file containing the SDP problem in -SDPA sparse format, final solution is the optional name of a file in which -to save the final solution, and initial solution is the optional name of a file -from which to take the initial solution. - The following example shows how CSDP would be used to solve a test prob- -lem. - ->csdp theta1.dat-s -CSDP 6.2.0 -Iter: 0 Ap: 0.00e+00 Pobj: 1.4644661e+04 Ad: 0.00e+00 Dobj: 0.0000000e+00 -Iter: 1 Ap: 9.31e-01 Pobj: 5.7513865e+03 Ad: 1.00e+00 Dobj: 8.0172003e+01 -Iter: 2 Ap: 9.21e-01 Pobj: 2.3227402e+02 Ad: 1.00e+00 Dobj: 8.2749235e+01 -Iter: 3 Ap: 9.30e-01 Pobj: 1.0521019e+01 Ad: 1.00e+00 Dobj: 8.4447722e+01 -Iter: 4 Ap: 1.00e+00 Pobj: 2.5047625e+00 Ad: 1.00e+00 Dobj: 7.2126480e+01 -Iter: 5 Ap: 1.00e+00 Pobj: 7.5846337e+00 Ad: 1.00e+00 Dobj: 4.2853659e+01 -Iter: 6 Ap: 1.00e+00 Pobj: 1.5893126e+01 Ad: 1.00e+00 Dobj: 3.0778169e+01 -Iter: 7 Ap: 1.00e+00 Pobj: 1.9887401e+01 Ad: 1.00e+00 Dobj: 2.4588662e+01 - - -Iter: 8 Ap: 1.00e+00 Pobj: 2.1623330e+01 Ad: 1.00e+00 Dobj: 2.3465172e+01 -Iter: 9 Ap: 1.00e+00 Pobj: 2.2611983e+01 Ad: 1.00e+00 Dobj: 2.3097049e+01 -Iter: 10 Ap: 1.00e+00 Pobj: 2.2939498e+01 Ad: 1.00e+00 Dobj: 2.3010908e+01 -Iter: 11 Ap: 1.00e+00 Pobj: 2.2996259e+01 Ad: 1.00e+00 Dobj: 2.3000637e+01 -Iter: 12 Ap: 1.00e+00 Pobj: 2.2999835e+01 Ad: 1.00e+00 Dobj: 2.3000020e+01 -Iter: 13 Ap: 1.00e+00 Pobj: 2.2999993e+01 Ad: 1.00e+00 Dobj: 2.2999999e+01 -Iter: 14 Ap: 1.00e+00 Pobj: 2.3000000e+01 Ad: 1.00e+00 Dobj: 2.3000000e+01 -Success: SDP solved -Primal objective value: 2.3000000e+01 -Dual objective value: 2.3000000e+01 -Relative primal infeasibility: 5.55e-17 -Relative dual infeasibility: 3.93e-09 -Real Relative Gap: 7.21e-09 -XZ Relative Gap: 7.82e-09 -DIMACS error measures: 5.55e-17 0.00e+00 1.00e-07 0.00e+00 7.21e-09 7.82e-09 -Elements time: 0.001091 -Factor time: 0.000620 -Other time: 0.016636 -Total time: 0.018348 - One line of output appears for each iteration of the algorithm, giving the -iteration number, primal step size (Ap), primal objective value (Pobj), dual step -size (Ad), and dual objective value (Dobj). The last eight lines of output show -the primal and dual optimal objective values, the XZ duality gap, the actual -duality gap, the relative primal and dual infeasibility in the optimal solution. - The last four lines give the time in seconds used by various steps in the -algorithm. The first line, “Elements” shows the time spent in constructing the -Schur complement matrix. The second line, “Factor” shows the time spent in -factoring the Schur complement matrix. The third line, “Other” shows the time -spent in all other operations. The fourth line gives the total time used in solving -the problem. Note that the times given here are “wall clock” times, not CPU -time. On a system that is running other programs, the wall clock time may be -considerably larger than the CPU time. On multiprocessor systems, the wall -clock time will not include all of the CPU time used by the different processors. -The reported time will typically vary on repeated runs of CSDP, particularly -for small problems like the one solved here. - CSDP searches for a file named “param.csdp” in the current directory. If -no such file exists, then default values for all of CSDP’s parameters are used. If -there is a parameter file, then CSDP reads the parameter values from this file. -A sample file containing the default parameter values is given below. - -axtol=1.0e-8 -atytol=1.0e-8 -objtol=1.0e-8 -pinftol=1.0e8 -dinftol=1.0e8 - - -maxiter=100 -minstepfrac=0.90 -maxstepfrac=0.97 -minstepp=1.0e-8 -minstepd=1.0e-8 -usexzgap=1 -tweakgap=0 -affine=0 -printlevel=1 -perturbobj=1 -fastmode=0 - - The first three parameters, axtol, atytol, and objtol are the tolerances -for primal feasibility, dual feasibility, and relative duality gap. The parameters -pinftol and dinftol are tolerances used in determining primal and dual infea- -sibility. The maxiter parameter is used to limit the total number of iterations -that CSDP may use. The minstepfrac and maxstepfrac parameters deter- -mine how close to the edge of the feasible region CSDP will step. If the primal -or dual step is shorter than minstepp or minstepd, then CSDP declares a -line search failure. If parameter usexzgap is 0, then CSDP will use the ob- -jective function duality gap instead of the tr(XZ) gap. If tweakgap is set to -1, and usexzgap is set to 0, then CSDP will attempt to “fix” negative duality -gaps. If parameter affine is set to 1, then CSDP will take only primal–dual -affine steps and not make use of the barrier term. This can be useful for some -problems that do not have feasible solutions that are strictly in the interior of -the cone of semidefinite matrices. The printlevel parameter determines how -much debugging information is output. Use printlevel=0 for no output and -printlevel=1 for normal output. Higher values of printlevel will generate -more debugging output. The perturbobj parameter determines whether the -objective function will be perturbed to help deal with problems that have un- -bounded optimal solution sets. If perturbobj is 0, then the objective will not -be perturbed. If perturbobj is 1, then the objective function will be perturbed -by a default amount. Larger values of perturbobj (e.g. 100.0) increase the size -of the perturbation. This can be helpful in solving some difficult problems. The -fastmode parameter determines whether or not CSDP will skip certain time -consuming operations that slightly improve the accuracy of the solutions. If -fastmode is set to 1, then CSDP may be somewhat faster, but also somewhat -less accurate. - - - -SDPA sparse format example -========================== - For an example of how to setup these data structures, refer to the example -directory in the CSDP distribution. This directory contains a program that -solves the very small SDP - - max tr (CX) - tr A1 X = 1 - (8) - tr A2 X = 2 - X  0 -where   - 2 1 -  1 2  -   -  -  3 0 1  -  - C= -  0 2 0  -  (9) -  -  1 0 3  -  -  0  -   - 3 1 -  1 3  -   -  -  0 0 0  -  - A1 =  -  0 0 0  -  (10) -  -  0 0 0  -  -  1  - - - - -   - 0 0 -  0 0  -   -  -  3 0 1  -  - A2 =  -  0 4 0 . -  (11) -  -  1 0 5  -  -  0  - In this problem, the X, Z, A1 , A2 and C matrices have three blocks. The -first block is a 2 by 2 matrix. The second block is a 3 by 3 matrix. The third -block is a diagonal block with 2 entries. - In addition to setting up and solving this problem, the example program -calls the write prob() routine to produce a file containing the SDP problem in -SDPA sparse format. This is stored in the file prob.dat-s. - -2 -3 -2 3 -2 -1.000000000000000000e+00 2.000000000000000000e+00 -0 1 1 1 2.000000000000000000e+00 -0 1 1 2 1.000000000000000000e+00 -0 1 2 2 2.000000000000000000e+00 -0 2 1 1 3.000000000000000000e+00 -0 2 1 3 1.000000000000000000e+00 -0 2 2 2 2.000000000000000000e+00 -0 2 3 3 3.000000000000000000e+00 -1 1 1 1 3.000000000000000000e+00 -1 1 1 2 1.000000000000000000e+00 -1 1 2 2 3.000000000000000000e+00 -1 3 1 1 1.000000000000000000e+00 -2 2 1 1 3.000000000000000000e+00 -2 2 2 2 4.000000000000000000e+00 -2 2 3 3 5.000000000000000000e+00 -2 2 1 3 1.000000000000000000e+00 -2 3 2 2 1.000000000000000000e+00 - -The 2 in the first line indicates that this problem has two constraints. The 3 in -the second line indicates that there are three blocks in the X and Z matrices. -The third line gives the sizes of the three blocks. Note that the third block’s -size is given as -2. The minus sign indicates that this is a diagonal block. The -fourth line gives the values of the right hand sides of the two constraints. - The remaining lines in the file describe the entries in the C, A1 , and A2 -matrices. The first number in each line is the number of the matrix, with 0 -for the C matrix. The second number specifies a block within the matrix. The -third and fourth numbers give the row and column of a nonzero entry within -this block. The fifth number gives the actual value at that position within the - - - - -block. Comparing this file to the problem statement above can be helpful in diff --git a/apn/lean/docs/loogle/LICENSE b/apn/lean/docs/loogle/LICENSE deleted file mode 100644 index 813da297..00000000 --- a/apn/lean/docs/loogle/LICENSE +++ /dev/null @@ -1,71 +0,0 @@ -Apache License 2.0 (Apache) -Apache License -Version 2.0, January 2004 -http://www.apache.org/licenses/ - -TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - -1. Definitions. - -"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. - -"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. - -"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. - -"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. - -"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. - -"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. - -"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). - -"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. - -"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." - -"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. - -2. Grant of Copyright License. - -Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. - -3. Grant of Patent License. - -Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. - -4. Redistribution. - -You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: - -1. You must give any other recipients of the Work or Derivative Works a copy of this License; and - -2. You must cause any modified files to carry prominent notices stating that You changed the files; and - -3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and - -4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. - -You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. - -5. Submission of Contributions. - -Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. - -6. Trademarks. - -This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. - -7. Disclaimer of Warranty. - -Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. - -8. Limitation of Liability. - -In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. - -9. Accepting Warranty or Additional Liability. - -While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. - diff --git a/apn/lean/docs/loogle/loogle.md b/apn/lean/docs/loogle/loogle.md deleted file mode 100644 index 8af84e9f..00000000 --- a/apn/lean/docs/loogle/loogle.md +++ /dev/null @@ -1,84 +0,0 @@ - -# Loogle - -Loogle searches Lean and Mathlib definitions and theorems. - -## Query language - -Loogle finds definitions and lemmas in various ways: - -1. By constant: - `Real.sin` - finds all lemmas whose statement somehow mentions the sine function. - -2. By lemma name substring: - `"differ"` - finds all lemmas that have `"differ"` somewhere in their lemma _name_. - -3. By subexpression: - `_ * (_ ^ _)` - finds all lemmas whose statements somewhere include a product where the second argument is - raised to some power. - - The pattern can also be non-linear, as in - `Real.sqrt ?a * Real.sqrt ?a` - - If the pattern has parameters, they are matched in any order. Both of these will find `List.map`: - `(?a -> ?b) -> List ?a -> List ?b` - `List ?a -> (?a -> ?b) -> List ?b` - -4. By main conclusion: - `|- tsum _ = _ * tsum _` - finds all lemmas where the conclusion (the subexpression to the right of all `→` and `∀`) has the - given shape. - - As before, if the pattern has parameters, they are matched against the hypotheses of - the lemma in any order; for example, - `|- _ < _ → tsum _ < tsum _` - will find `tsum_lt_tsum` even though the hypothesis `f i < g i` is not the last. - -If you pass more than one such search filter, separated by commas, Loogle will return lemmas which match _all_ of them. -The search -`Real.sin, "two", tsum, _ * _, _ ^ _, |- _ < _ → _` -would find all lemmas which mention the constants `Real.sin` and `tsum`, have `"two"` as a -substring of the lemma name, include a product and a power somewhere in the type, *and* have a -hypothesis of the form `_ < _` (if there were any such lemmas). Metavariables (`?a`) are assigned independently in each filter. - -## CLI usage - -The loogle binary searches any Lake project of the same Lean toolchain. Run it -from the project via `lake env` (which supplies the olean search path): - - $ lake env loogle --module Mathlib '(List.replicate (_ + _) _ = _)' - Found 5 declarations mentioning List.replicate, HAdd.hAdd and Eq. - Of these, 3 match your patterns. - - List.replicate_add - List.replicate_succ - List.replicate_succ' - -The first call builds the search index (slow); by default loogle caches it on -disk next to the module's `.olean` so subsequent calls are fast, and quietly -rebuilds it whenever the underlying `.olean`s change. (In this image the -Mathlib index is prebuilt, so queries are fast from the start.) - - USAGE: - loogle [OPTIONS] [QUERY] - - OPTIONS: - --help - --interactive, -i read querys from stdin - --json, -j print result in JSON format - --module mod import this module (default: Mathlib) - --path path search for .olean files here (default: the build time path) - --index-mode MODE how to manage the on-disk search index. One of: - use (default) load if present and up-to-date, - otherwise build and write - read load existing index; refuse to start if it - is missing or out of date - write always (re)build the index and write it - none build in memory and discard on exit - --index-file PATH override the default index path. The default lives - next to the root module's .olean (with .loogle-index - extension); pass this if that location is read-only. - --max-results n limit the number of returned hits (default: 200) diff --git a/apn/lean/docs/lrslib/LICENSE b/apn/lean/docs/lrslib/LICENSE deleted file mode 100644 index a43ea212..00000000 --- a/apn/lean/docs/lrslib/LICENSE +++ /dev/null @@ -1,339 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 675 Mass Ave, Cambridge, MA 02139, USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - Appendix: How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) 19yy - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) 19yy name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. diff --git a/apn/lean/docs/lrslib/lrs-userguide.md b/apn/lean/docs/lrslib/lrs-userguide.md deleted file mode 100644 index 248ee135..00000000 --- a/apn/lean/docs/lrslib/lrs-userguide.md +++ /dev/null @@ -1,1065 +0,0 @@ - - -   - -###   David Avis          avis@cs.mcgill.ca     [http://cgm.cs.mcgill.ca/~avis](http://cgm.cs.mcgill.ca/%7Eavis) - -[What's new](./whatsnew.html) - -[Introduction](#Introduction) - -[lrs: installation and usage](#Installation%20Section) - -[mplrs: installation and usage](#mplrs) - -[lrsnash: installation and usage -](#nash) - -  - -[File formats](#file) - -[Basic options](#Options) - -[Arithmetic packages ](#Arithmetic%20Packages) - -[Estimation](#Estimation) - - - -[Extreme point enumeration and eliminating redundant -inequalities](#redund) [](#fourier) - -[Linear programming](#Linear%20Programming) - -[Fourier elimination](#fourier) - -[(New)Testing redundancy in projections](#hpred) - -[Volume and triangulation](#Volume%20Computation) - -[Voronoi Diagrams and Delaunay Triangulations - -](#Voronoi%20Diagrams) - -[Linearities](#Linearities) - -[Timing, interrupts and restarts -](#timing) - -[(New)Vertex/Facet cross reference listing -](#hvref) - -[Error messages and troubleshooting](#Timing%20and%20Interrupts) - -[Hints and comments](#Hints%20and%20Comments) - -[Acknowledgements and References](#Acknowledgements) - ------------------------------------------------------------------------- - ------------------------------------------------------------------------- - -### Introduction - -A polyhedron can be described by a list of inequalities -(*H-representation)* or as by a list of its vertices and extreme rays -(*V-representation).lrs* is a C program that converts a H-representation -of a polyhedron to its V-representation, and vice versa.  These problems -are known respectively at the *vertex enumeration(VE)* and *convex -hull(CH) problems*. -Fukuda's [FAQ page](https://people.inf.ethz.ch/fukudak/soft/soft.html)   -contains a more detailed introduction to the problem, along with many -useful tips for the new user. - -*lrs* is based on the *reverse search* algorithm developed with Komei -Fukuda, see -[(](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AF92b.ps)[AF](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AF92b.ps)[1992)](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AF92b.ps) -, modified to use lexicographic pivoting  and implemented in rational -arithmetic. It uses limited multithreading via OpenMP.  -[(](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98a.ps)[Av](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98a.ps)[1998a)](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98a.ps) -contains a technical description, and -[(](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98b.ps)[Av](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98b.ps)[1998b)](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98b.ps) -contains some computational experience. -*mplrs* is a full parallel version of *lrs* based on Open MPI for -distributed systems, developed with Skip Jordan, see -[(AJ2015)](http://arxiv.org/abs/1511.06487). - -The input files are in *Polyhedra format* , developed with Fukuda. The -format is essentially self-dual, and the output file produced can be -read in as an input file, with very minor modifications, to perform the -reverse transformation. This format is compatible with that  used in -Fukuda's *[cddlib ](https://www.inf.ethz.ch/personal/fukudak/cdd_home/)* -package, which performs the same transformations using a version of the -*double description method*.  The program -[normaliz](https://www.normaliz.uni-osnabrueck.de/) provides a parallel -version of the double description method. Another program using the same -file format is the primal-dual method -*[pd](http://www.cs.unb.ca/profs/bremner/pd/),* developed by Bremner, -Fukuda and Marzetta .  It is essentially dual to *lrs,* and is very -efficient for computing H-representations of simple polyhedra, and -V-representations of simplicial polyhedra. It will compute the volume of -a polytope given by an H-representation. Links to additional VE/CH -programs are given -[here](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/links.html). - -Polyhedra handled by *lrs * need not be full dimensional  and may -contain input linearities and redundant columns .  *lrs* accepts either -integer or rational input, and produces integer or rational output. All -computations are done exactly using hybrid arithmetic, starting with 64 -bits and moving to 128 bits and extended precision (GMP or built-in) if -necessary, see [(AJ2021)](https://arxiv.org/abs/2101.12425).  Since it -is a pivot based method, *lrs* can be very slow for degenerate inputs: -i.e. H-representations of non-simple polyhedra, and V-representations of -non-simplicial polyhedra. On the other hand, it does not store the -vertices/ rays or facets produced, so for very large problems it may be -the only method that can solve the problem.  Using mplrs, even with just -a few cores, significantly speeds up the computation. A discussion of -various vertex enumeration/convex hull methods and the types of -polyhedra that cause them to behave badly is contained in [(ABS -1997).](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/ABS96a.ps)  A more -recent discussion with extensive empiral tests can be found in -[(AJ2017)](https://arxiv.org/abs/1511.06487).  Considerable technical -assistance over several decades has been provided by David Bremner. - - Functions of *mplrs*/*lrs* include: - -- [V-H transformation](#Installation%20Section): converting an - H-representation to a V-representation and vice versa -- [Estimating](#Estimation) the number of vertices/rays or facets of a - polytope, and estimating the total running time (lrs only) -- [Triangulating and computing the volume](#Volume%20Computation) of a - polytope given by a V-representation -- Removing [redundancy](#redund) from an H or V-representation and - computing a [minimum representation](#redund). Parallel version in - mplrs (v7.3 new) -- [Projecting](#fourier) a polyhedron to a subset of its variables - (Fourier elimination). Parallel version in mplrs (v7.3 new) -- Determining if an inequality is [redundant in computing the - projection](#hpred) to a subset of its variables (uses SMT-solver, - v7.2 new) -- Solving [linear programming](#Linear%20Programming) problems in exact - arithmetic (Simplex method, lrs only) -- Computing the [Voronoi](#Voronoi%20Diagrams) vertices and rays for an - input set of data points and the corresponding [Delaunay - triangulation](#Voronoi%20Diagrams) -- [Eliminating](#eliminate) variables in linearities in - H-representations and [extracting columns](#eliminate) from - V-representations (lrs only) -- Computing all [Nash equilibria](#nash) for 2-person matrix games - (lrsnash) -- Computing a [cross reference table](#hvref) of vertices/rays vs - facets -- The ability to [suspend and restart](#timing) execution at any time - for H-V transformations - -Redundancy removal involves the removal of any inequalities that are not -required to represent the polyhedron in an H-representation. For a -V-representation it is  the problem of evaluating the extreme points and -extreme rays. Finding a minimum representation involves locating any -hidden linearities in the input file. These problems are normally  -considerably easier than the H to V and V to H transforamtions performed -as they are performed by linear programming. In some cases, redundancy -can greatly slow the processing time taken for H-V transformation using -*lrs/mplrs,* and it is advisable to remove any redundancy and hidden -linearities from the input file before starting a long run. - -These programs can be distributed freely under the GNU GENERAL PUBLIC -LICENSE. Please read the file COPYING carefully before using.  Please -inform the authors of any interesting applications for which these -programs were helpful. - ------------------------------------------------------------------------- - -lrslib installation and usage - -Package install is the simplest for linux or WSL/linux users, but may -not contain the latest version of lrslib: - -Debian/Ubuntu (2025.3.25: v7.1):  sudo apt install lrslib     -(maintained by David Bremner \ ) - -Fedora (2025.3.25: v7.3):              sudo dnf install lrslib     -(maintained by Jerry James \ ) - -Additional instructions for installing **mplrs**, a multithreaded -implementation of **lrs** using MPI, are [here](#mplrs). - -Precompiled binaries lrs, lrsgmp for some Linux, Apple and Windows -machines are -[here](https://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/archive/binaries/). -These may be slower for problems requiring very long integers. - -Install from source code: - -- From lrs home page, click on "Download" and retrieve the file - lrslib-073.tar.gz -- Unpack with: -- Go to the new directory --  make lrs with various arithmetic packages (it may be necessary to - edit makefile to set the path to the gmp library) - -        This produces binaries **lrs** (hybrid arithmetic) and the -usually slower  **lrsgmp** (GMP arithmetic) - -         For compilers without \_\_int128 and/or OpenMP support you will -need to edit the makefile as indicated at the beginning of that file. - - -- You will need to have write permission to /tmp to run the hybrid - arithmetic programs lrs. Temporary files are normally removed before - termination. - -- If  you do not have GNU MP installed you can try using the built in - lrs [arithmetic package](#Arithmetic%20Packages): -- Test the program  - -This is a list of the 8 vertices with each co-ordinate +/- 1.  The -\*\*\*\*\* should be replaced by the actual number, 8, of vertices. -Since *lrs* does not save the output produced, it does not know this -value until the execution terminates. This output is now essentially the -same as file cube.ext. To complete the test type: - -Now the output produced is essentially the file cube.ine, with the -inequalities appearing in a different order. - - -Binaries produced by % make lrs or % make lrsgmp - -            **lrs**                 hybrid [arithmetic -package](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/USERGUIDE63.html#Arithmetic%20Packages) -starting with  64 bit arithmetic, then 128 bit, then GMP. -            **lrsgmp**        GMP arithmetic only -            -          - -Additional instructions for installing **mplrs**, a multithreaded -implementation of **lrs** using MPI, are [here](#mplrs). - -###  File formats - -  - -**Note for cdd users**: *lrs* uses essentially the same file format as -*cdd*. Files prepared for *cdd* should work with little or no -modification. Note that  the V-representation corresponds to the "hull" -option in *cdd*. Options specific to *cdd* can be left in the input -files and will be ignored by *lrs*.  Note the input files for *lrs* are -read in free format, after the line **m n rational** *lrs* will look for -exactly m\*n rationals or integers separated by white space (blank,  -carriage return, tab etc.). *lrs* will not "drop" extra columns of input -if n is less than the number of columns supplied. - ------------------------------------------------------------------------- - -### Basic options    Also see:     [Online manual](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/man) - -**allbases** - -**bound  x                           **         // Use with -H-representation  - for lrs or nash // - -Either the maximize or minimize option should be selected. x is an -integer or rational. -For maximization (resp. minimization) the reverse search tree is -truncated  whenever the current objective value is less (resp. more) -than x . - - -**cache n** - -**debug  startingbasis endingbasis** - -> Print out cryptic but detailed trace, dictionaries etc. starting at -> \#B=startingbasis and ending at \#B=endingbasis. **debug 0 0** gives a -> complete trace. - -**digits n    **            // placed before the begin statement// - -**dualperturb -** - -If lrs is executed with the maximize or minimize option, the reverse -search tree is rooted at an optimum vertex for this function. -If there are mulitiple optimum vertices, the output will often not be -complete. This option gives a small perturbation to the objective to -avoid this. -A warning message is given if the starting dictionary is dual -degenerate**.** - - -**eliminate** **k   i₁ i₂ ... -i_(k) **   **                                              new in v7.2 -** - -   (H-representation) Eliminates k variables in an H-representation -corresponding to cols **i₁ i₂ i ... i_(k )** by projection onto the -  remaining variables using the Fourier-Motzkin method.  Variables are -eliminated in the order given and redundancy is removed -  after each iteration. -  (V-representation) Delete the k given columns from the input matrix -and remove redundancies (cf. extract where redundancies -  are not removed). -  Column indices are between 1 and n-1 and column zero cannot be -eliminated.  The output is a valid lrs input file.  -  See [Fourier -elimination](file:///C:/Users/avis/Desktop/User%27s%20Guide%20for%20lrs.html#fourier), -also **project** and **extract - -** -**estimates k**     Estimate the output size. Used in conjunction with -maxdepth - see -[Estimation.](file:///C:/Users/avis/Desktop/User%27s%20Guide%20for%20lrs.html#Estimation) - -  - -**extract k   i₁ i₂ ... i_(k          )** (lrs only)  v7.2** -      ** (H-representation) A preprocessing step to remove linearities -(if any) in an H-representation and resize the A matrix.  The -       output as a valid lrs input file. The resulting file will not -contain any equations but may not be full dimensional as there -       may be additional linearities in the remaining inequalities. -Options in the input file are stripped.  The user can specify -       the **k** columns  **i₁ i₂ ... i_(k)** to retain otherwise if k=0 -the columns are considered in the order 1,2,..n-1.  Linear dependent -       columns are skipped and additional indices are taken from -1,2,...,n-1 as necessary.  If there are no linearities in the input -       file the given columns are retained and the other ones are -deleted. -       (V-representation) Extract the given columns from the input file -outputing a valid lrs input file.  Options are stripped.** -      ** (See also **eliminate** and **project**)** - -geometric  **               // H-representation  or voronoi option only -// - -          For more information and an example see Geometric Rays in -[Hints and Comments](#Hints%20and%20Comments) . - -**incidence** -           This option automatically switches on **printcobasis** , so -see below for a description of this option first. - -> Can be used with printcobasis n. (Ver 4.2b) -> -> For input H-representation, indices of all input inequalities that -> contain the vertex/ray that is about to be output. For a simplicial -> face, there is no new output, since these indices are already listed. -> Otherwise, the additional tight inequalities are listed after a colon. -> Eg: -> **V#1 R#0 B#1 h=0 facets  12 14 15 16 : 9 10 11 13 I#8 det= 8** -> ** 1  0  0  0  1** -> The vertex **0 0 0 1** satisfies 8 input inequalities as equations, as -> indicated by **I#8** : those with indices **12,14,15,16** are in the -> cobasis, and those with indices **9, 10, 11, 13** are in the basis. -> For a ray: -> **V#1 R#5 B#1 h=0 facets  5 9\* 10 11 12 13 : 2 3 4 I#8 det= 8** -> ** 0  1  1  0  0  1  1** -> Here the ray **1  1  0  0  1  1** lies on 8 inequalities, with indices -> **5 10 11 12 13** in basis and **2 3 4 i**n cobasis. The starred index -> **9\*** indicates that the ray is terminated by the input inequality -> 9. This inequality is in the cobasis and defines the vertex from which -> the ray starts. -> -> For input V-representation, indices of all input vertices/rays that -> lie on the facet that is about to be output: -> **F#5 B#3 h=2 vertices/rays  7 8\* 11 13 15 : 1 3 5 9 I#8 det= 16** -> **1 -1  0  0  0** -> The facet generated by inequality x₁ \<= 1 contains 8 input vertices, -> as indicated by I#8: those with indices **7,11,13,15** are in the -> cobasis, and those with indices **1 3 5 9** are in the basis.The -> starred index **8\*** indicates that this vertex  is also in the -> cobasis, but is not contained in the facet. It arises due to the -> lifting operation used with input V-representations. - -**\#incidence** - -> The same as printcobasis. Included for compatability with *cdd.* - -**linearity  k  i₁ i₂ i ... i_(k)** - -> The input contains k linearities in rows **i₁ i₂ i ... i_(k)** of the -> input file are equations. See [Linearities.](#Linearities) - -**maxdepth k** - -**maximize ** **a₀ a₁ ... -a_(n-1)** **                                          ** // -H-representation  only // -**minimize  ** **a₀ a₁ ... -a_(n-1)**                                           // H-representation  -only // - -If used with lrs the starting vertex maximizes (or minimizes) the -function  a₀ + a₁ x ₁ + ... + a_(n-1) x_(n-1). -The dualperturb option may be needed to avoid dual degeneracy. -See Nash Equilibria and  [Linear Programming](#Linear%20Programming) - -**maxcobases n        ** //from Version 6.0 // -       After n cobases have been generated lrs terminates and returns -restart data for all unexplored roots of subtrees (except for leaves -which are output). These subtrees are the unexplored siblings on the -path back to the root of the reverse search tree. Used by -[mplrs](#mplrs) to break up large subtrees into smaller pieces. -** -maxincidence n  k         //from v.7.3// -      ** Prunes the search tree when the depth is at least k and the -current vertex/facet has incidence at least n.  -       Using **verbose** a message is printed whenever the search tree -is pruned.** - -maxoutput n**    -       Limits number of output lines produced (either vertices+rays or -facets) to n -** -mindepth k** - -**nonnegative                     ** // This option must come before the -begin statement// -                                                                                            -//H-representation only // -           Bug: Can only be used if the origin is a vertex of the -polyhedron  - -> For problems where the input is an H-representation of the form -> b+Ax\>=0, x\>=0 (ie. all variables non-negative, all constraints -> inequalities) it is not necessary to give the non-negative constraints -> explicitly if the nonnegative option is used. This option cannot be -> used for V-representations, or with the linearity option (in which -> case the linearities will be treated as inequalities). This option may -> be used with redund , but the implied nonnegativity constraints are -> not tested themselves for redundancy. To test everything it is -> necessary to enter the nonnegativity constraints explicitly in the -> input file. (In Ver 4.1, the origin must be a vertex). - -**printcobasis  k                                 ** - -**printslack              **          // Use with H-representation // - - -lrs prints a list of the indices of the input inequalities that are -satisfied strictly for the current vertex, ie. corresponding slack -variable is positive. -If nonnegative is set, the list will also include indices n+i for each -decision variable x_(i) which is positive. - - - -**project** ****k   i₁ i₂ ... -i_(k)**                                                  new in v7.2 -** - -       (H-representation) Project the polyhedron onto the **k** -variables corresponding to cols **i₁ i₂ ... i_(k)** using the -Fourier-Motzkin -       method. Column  indices are between 1 and n-1 and column zero is -automatically retained.  Variables not contained in the list -       are eliminated using a heuristic which chooses the column which -minimizes the product of the number of positive and negative -       entries.  Redundancy is removed after each iteration using linear -programming. -       (V-representation) Extract the k given columns from the input -matrix and remove redundancies. Column  indices are between 1 -       and n-1 and column zero is automatically extracted (cf. extract -where redundancies are not removed). -       The output as a valid lrs input file.  See [Fourier -elimination](#fourier), also **eliminate** and **extract** - - -** -** -****redund start end                      new in v7.1 -          **** Check input line numbers from **start** to **end** and -remove any redundant lines. -            **redund 0 0**  will check all input lines.  See -[redund](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/USERGUIDE71.html#redund)** - -redund_list k   i₁ i₂ ... i_(k                 )** ****new in v7.1**** - -Check the **k** input line numbers with indices **i₁ i₂ ... i_(k)**  -from and remove any redundant lines. See [redund](#redund) - - -**restart  V# R# B# depth {facet \#s or vertex/ray \#s**}  -**\[integervertices n**\]                                               -                    /\* new in V 7.0 \*/              - -  - -****startingcobasis i₁ i₂ i ... i_(n-1)** -** - -******testlin      (before the begin line only)   H-representation -only**  (new 7.3)**** **** -**   ** - -**threads  n**     (new in 7.3) lrs only - -**truncate                                           ** // -H-representation only //       - -> The reverse search tree is truncated(pruned)  whenever a new vertex is -> encountered. Note: This does note necessarily produce the set of all -> vertices adjacent to the optimum vertex in the polyhedron, but just a -> subset of them. See -> [here](http://cgm.cs.mcgill.ca/%7Eavis/C/lrslib/lexpos.html) for a -> description of how to use this option. - -**verbose** - -> Print slightly more detailed information about the run. - -**volume                                             ** // -V-representation  only // - -**voronoi                                             ** // -V-representation  only - place immediately after end statement // - ------------------------------------------------------------------------- - -###   Linear Programming              - -**lponly** - -             and one of the options maximize or minize: - -**maximize a₀ a₁ ... a_(n-1)**                                           -// H-representation  only // - -**minimize a₀ a₁ ... -a_(n-1)**                                             // -H-representation  only // - -To print the dictionary at a few key points also include the option: - -**verbose -** - -**New in V4.2.** Dual variables are now printed at termination. If the -linearity option is used, only a partial list of dual variables will be -given. -                       Dual variable y_(i) refers to inequality number i -in the input. - ------------------------------------------------------------------------- - -### Volume and triangulation - -*lrs* can be used to compute the volume of a full dimensional polytope -given as a V-representation. This follows from the fact that lex-postive -bases form a triangulation of the facets, and that a V-representation is -always lifted. See "Theoretical Description" on lrs home page for some -remarks on this. The option - -**volume    ** -                                                                        -// V-representation only // - -will cause the volume to be computed. For input cube.ext, the output -is: -**\*Volume=8** - -The triangulation can be output by adding also the option verbose. -This would give the output: - -F#0 B#1 h=0 vertices/rays  4 6 7 8 I#8 det= 8 - 1  1  0  0 - 1  0  1  0 - 1  0  0  1 -F#3 B#2 h=1 vertices/rays  4 5 6 7 I#8 det= 8 -F#3 B#3 h=2 vertices/rays  3 4 5 7 I#8 det= 8 - 1 -1  0  0 -F#4 B#4 h=3 vertices/rays  2 3 4 5 I#8 det= 8 - 1  0  0 -1 -F#5 B#5 h=4 vertices/rays  1 2 3 5 I#8 det= 8 -F#5 B#6 h=2 vertices/rays  2 4 5 6 I#8 det= 8 - 1  0 -1  0 -end -\*Sum of det(B)= 48 -\*Volume= 8 - -Each of the 6 bases corresponds to a simplex. -The first simplex is composed of vertices 4 6 7 8, second simplex is 4 5 -6 7, etc. - -If the **volume** option is applied to an H-representation, the results -are not predictable. If the option is applied to a V-representation of - a polytope that is not full dimensional, the volume of a projected -polytope is computed. The projection used is to the lexicographically -smallest coordinate subspace, see [Avis, Fukuda, Picozzi -(2002)](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AFP02a.ps).  - -For polytopes given by a H-representation, it will first be necessary to -compute the V-representation. - ------------------------------------------------------------------------- - -### Voronoi diagrams and Delaunay triangulations - -*lrs* can be used the compute the V-vertices of a Voronoi diagram of a -set of data points in n-1 dimensional space. To do this we use a -standard lifting procedure (see, e.g., Edelsbrunner, "Algorithms in -Combinatorial Geometry," pp 296-297) . Each point is mapped to a half -space tangent to the parabaloid in n dimensions, by the mapping: - -p₁  , p₂  , ...., p _(n-1)     -\>    (p₁ ²  +   p₂² +  ...   +  -p_(n-1)²  ) - 2 p₁  x ₁  - 2 p₂  x₂ - .... - 2  p _(n-1) x_(n -1 ) + x -_(n)\>= 0 - -*lrs* is applied to the H-representation so created.  This -transformation is performed automatically for a V-representation if the - -**voronoi         ** // V-representation only - place immediately after -end statement // - -option is specified. -**Note**: The input file must consist entirely of data points (no rays), -i.e.. there must be a one in column one of each line. The **volume** -option should not be used, since the volume reported will not be the -volume of the original V-representation. -The output will consist of the Voronoi vertices (columns beginning with -a one) and Voronoi rays (columns beginning with zero) for the Voronoi -diagram defined on the data points.  If the **printcobasis** option is -given, the n "**data points**" indices produced will tell which set of -input data points corresponds to the given Voronoi vertex or ray. In -case of degeneracies, a given Voronoi vertex may be generated by more -than n of the input data points. In this case, use of the **allbases** -option will cause all  sets of n input data points corresponding to a -Voronoi vertex to be printed. Each cobasis will define a **Delaunay -triangle** in the dual. For Voronoi rays, the immediately preceding  -cobasis is the cobasis of the the Voronoi vertex from which the ray -emanates.  The index followed by a **\*** is the data point to drop in -order to generate the ray. If the **geometric** option is given the -correspondence between Voronoi rays and Voronoi vertices will be -produced automatically. - -**Example:** Compute the Voronoi diagram and Delaunay triangulation of -the planar point set (0,0), (2,1), (1,2), (0,4), (4,0), (4,4) (2,-4). - -[TABLE] - - - - - -[TABLE] - -Visualizations made using [GeoGebra](https://www.geogebra.org). - -###   redund: extreme point enumeration and eliminating redundant inequalities     (new options parallel version from v7.1) - -###   minrep: finding a minimum representation of an H- or V-representation      (new options parallel version from v7.3) - -A convex hull problem that occurs frequently is to enumerate the extreme -points (vertices) of a given set of input points. This problem is in -fact much simpler than the problem of finding the facets of the given -input point set. It can be solved by linear programming.  The dual -problem is to remove redundant inequalities from an H-representation. An -input  inequality is redundant if it can be deleted without changing the -polyhedron. It is strongly redundant if it is not satisfied as strict -inequality by any feasible point. A vertex/ray in a V-representation is -strongly redundant if it is strictly interior to the convex hull. - -An H-representation may contain "hidden linearities" or inequalities -that are always satisfied as equations. A similar situation occurs in a -V-representation where the convex hull contains a line. The minimum -representation problem is to identify all linearities in an input file, -output them explicity using the linearity option, and then remove any -remaining redundant rows. The dimension of the input set is output at -the end of the computation. - -Redundancy removal can be obtained by using the lrs clone redund or by -lrs via the redund/redund_list options described above. - -A minimum representation can be obtained by using the lrs clone minrep -or by lrs via the testlin (before the begin line) and redund/redund_list -options. -mplrs can compute a minimum representation in parallel by use of the --minrep command line argument. Due to technical issues in the -parallelization mplrs does not do redundancy removal without also -computing a minimum representation. - -The ouput will be streamed if the verbose option is included after the -end line. -On each line \*nr indicates non-redundant, \*re indicates redundant, -\*sr indicates strongly redundant, and \*li indicates linearity. - -**Usage:** -(1) **With options**  (allows partial redundancy checking for large -inputs) - -Add the [redund](#redopt) or [redund_list](#redopt) option after the end -statement of a H- or V-representation. -Execute **% lrs filename**  **or   %mpirun -np \ mplrs -filename** - -If more than one redund/redund_list option is in the input file the last -one read takes priority. - -(2) **Without options**  (complete redundancy check of all input lines, -overidden by redund/redund_list option in input) - -To remove input lines that are not vertices/rays from a V-representation -or redundant inequalities from an H-representation use the command: - -For example, using the file mit.ine from the distribution: - -          % redund mit.ine - -> \*redund:lrslib v.7.1 2020.5.23(64bit,lrslong.h,overflow checking) -> -> \*Input taken from file mit.ine -> mit.ine -> \*mulint   : max(\|a\|,\|b\|) \> 2147483647 -> -> \*redund2 found - restarting -> \*redund:lrslib v.7.1 2020.5.23(128bit,lrslong.h,overflow checking) -> -> \*Input taken from file mit.ine -> mit.ine -> \*row 75 was redundant and removed -> \*row 77 was redundant and removed -> \*row 89 was redundant and removed -> -------------------------- -> \*row 709 was redundant and removed -> H-representation -> begin -> 708  9  rational ->  36  0  0 -2 -2 -1  0  0  0 -> ---------------------------- ->   ->  0  0  0  0  0  0  0  0  1 -> end -> \*Input had 729 rows and 9 columns: 21 row(s) redundant -> \*Overflow checking on lrslong arithmetic -> \*redund:lrslib v.7.1 2020.5.23(128bit,lrslong.h) - -From this output we first see that redund tried 64 bit arithmetic but -detected an overflow and reran with 128 bit arithmetic. -It found 21 redundant rows which were removed from the file. -The resulting output file can be used directly with lrs. -In fact, lrs works best if the input is non-redundant, see the section -[Redundancy vs Degeneracy.](#Hints%20and%20Comments) - ------------------------------------------------------------------------- - -### Linearities    - - -**linearity  k  i₁ i₂ i ... i_(k)** - -> The input file contains k linearities. If the input is a -> H-representation, the rows **i₁ i₂ i ... i_(k)** of the input file are -> equations. For a V-representation, the rows with these indices should -> begin with zero in column one, and will be interpreted as lines rather -> than rays.  Linearities defined on the input vertices of a -> V-representation are not defined, but the program will accept them and -> produce some output. Each of the indice **i_(k)** must be a distinct -> number between **1** and **m**. With an  H-representation, linearities -> are useful for enumeration of vertices on a facet or lower dimensional -> subspace. For example the file: -> -> **cube_ridge** -> **\*cube of side 2 centred at the origin** -> **H-representation** -> **linearity 2  1 5** -> **begin** -> **6 4 rational** -> **1 1 0 0** -> **1 0 1 0** -> **1 0 0 1** -> **1 -1 0 0** -> **1 0 -1 0** -> **1 0 0 -1** -> **end** -> -> causes vertices to be enumerated on the ridge which is the -> intersection of the two facets -> -> x₁ = -1   and   x₂ = 1 -> -> so the output is the pair of vertices -> -> cube_ridge -> \*Input linearity in row(s) 1 5 -> V-representation -> begin -> 2  4  rational ->  1 -1  1  1 ->  1 -1  1 -1 -> end -> -> Specifying linearities in this way will often produce -> [redundancy](#Hints%20and%20Comments) , especially if the dimension of -> the problem is reduced considerably. As a preprocessing step, it is -> useful to apply to remove any redundancy by [*redund*](#redund). In -> the case of the above problem the output produced by *redund* is: -> -> cube -> \*Input linearity in row(s) 1 5 -> \*row 2 was redundant and removed -> \*row 4 was redundant and removed -> H-representation -> linearity 2 1 2 -> begin -> 4 4 rational ->  1  1  0  0 ->  1  0 -1  0 ->  1  0  0  1 ->  1  0  0 -1 -> -> and two redundant halfspaces were removed. -> -> Redundant columns are closely related to linearities. If we examine -> the V-representation of cube_ridge above we can see that it is just a -> line segment in 3 dimensional space. Further,  columns 2 and 3 are -> multiples of column 1. If lrs is applied to this file, the column -> redundancies give rise to two linearities, so the output will appear -> as the H-representation given above: geometrically the intersection of -> two planes (the linearities) with two half-planes (defining the -> endpoints of the line segment). -> -> In general, the representation of the linearity space is not unique, -> however the one produced by lrs should be the same as that produced by -> cdd. - - - ------------------------------------------------------------------------- - -### Error messages and troubleshooting - -The most common error occurs from an incorrect input file specification, -please check the section [File Formats](#file) carefully. In particular, -*lrs* does not check the type or number of input coefficients -specified.  After the line -**m n rational** -you must specify **exactly** m\*n rational or integer coefficients. They -are read  in **free format** , but normally each input facet or -vertex/ray is begun on a new line.  See [note for cdd -users.](#Note%20for%20cdd%20users) - -The following error messages are produced by *lrs* . They are  arranged -in alphabetic order. - -**Cannot find linearity in the basis -** - -> The linearity option was specified but a basis cannot be created. -> Check the linearity indices are all less than n-1 and are disitinct. - -**Data type must be integer of rational** - -**Digits must be at most 2295  Change MAX_DIGITS and recompile     (This -message does not appear if the default gmp arithmetic package is used)** - -**Invalid input: check you have entered enough data! -** - -> Usually means that end of file was reached before enough input data -> was read. - -** -Invalid Co-basis - does not have correct rank** - -**Maximize/minimize only valid for H-representation** - -**No begin line** - -**No data in file** - -**No feasible solution** - -**Starting cobasis indices must be distinct and in range 1 .. m** - -**Trying to restart from infeasible dictionary** - -**mplrs error messages** -** -Error: lponly option not supported - use lrs!** - -**The following message may be produced when building lrs on macOS** - -**OpenMP support not found, disabling OpenMP parallel build -** - - - - ------------------------------------------------------------------------- - -Hints and comments - -#### H- vs V- representation - - *lrs* is programmed to manipulate H-representations directly. A file -presented as a V-representation is processed by lifting it to a cone in -one higher dimension, which is treated internally as a H-representation. -If the input file is a polytope which contains the origin, then the user -has two options. Submit it as a V-representation and have it processed -as just described, or submit it as a H-representation, and interpret the -output as a list of facet inequalities rather than "vertices". Since -this will not be lifted, it will be processed in a different way by -*lrs*. Sometimes a degenerate V-representation may run more quickly as a -H-representation, and sometimes more slowly. To decide which -representation to use for a large problem, the user can run the -**estimates** option and choose the representation with fewest estimated -bases. -  - -#### Redundancy vs Degeneracy - -For an H-representation, an input is redundant if some inequality can be -deleted without changing the polyhedron. It is degenerate if (in d -dimensions) at least one vertex lies on d+1 or more facets.  Similarly -in a V-representation an input is redundant if some input point is not a -vertex of the convex hull.  It is degenerate if some facet contains d+1 -or more input points. The [options](#Options)   **printcobasis** and -**incidence** give degeneracy information. Degeneracy causes pivot  or -triangulation based methods such as *lrs* to  run slowly. Redundancy is -one cause of degeneracy, but it can be avoided by pre-processing the -input files. See section [redund: extreme Point Enumeration and -Redundant Inequalities](#redund) for instructions on how to do this. -This pre-processing is unnecessary if it is known that the input is -non-redundant. - -Even with redundant input removed a polyhedron may be highly degenerate. -In distribution directory ine/metric there are many highly degenerate -combinatorial polytopes. These are difficult problems for all vertex -enumeration/convex hull programs that use pivoting, such as *lrs*.  For -example, the file *cp6.ine* is a polytope with 368 facets in  16 -dimensions. It has 32 vertices, but computing these required the -evaluation of 4,844,923,002 bases!(see [Avis-Jordan, -2017](https://arxiv.org/abs/1511.06487)) - -#### Memory considerations - -The strong point of *lrs* is that it does not save the output produced, -so in theory it cannot run out of memory.  With cache size one all -memory is allocated at the beginning, so if *lrs* starts running it will -not run out of memory. It is possible however that the number of digits -required to do the calculations exceeds the amount specified on the -**digits** option, or the default. In practice, this problem will also -arise early in the computation. In any case, a message is printed and -the calculation can be restarted. In order to improve performance, some -dictionaries should be cached. The default of 10 can be overridden by -the **cache**option. If the dictionary is in the cache it does not need -to be recomputed when backtracking, reducing  processing time by about -40%. Since the cache is allocated dynamically, a cache size that is too -large can potentially use up large ammounts of machine memory. - -#### Geometric Rays - -A minimum V-representation of a polyhedron is a minimum set of vertices -and rays such that each point in the polyhedron can be expressed as a -convex combination of vertices plus a non-negative combination of rays. -For the cube, if we delete the inequality -x₃ \<= 1, i.e.. the line 1 0 0 -1 from file *cube.ine*, we get the -output: -**V-representation** -**\*\*\*\*\* 4 rational** -**1 1 1 -1** -**0 0 0 1** -**1 -1 1 -1** -**1 1 -1 -1** -**1 -1 -1 -1** -**end** -indicating the polyhedron is the convex combination of 4 vertices and 1 -ray. With the **geometric** option, we get the output: -**V-representation** -**begin** -**\*\*\*\*\* 4 rational** -**1 1 1 -1** -**0 0 0 1  \* 1 1 1 -1** -**1 -1 1 -1** -**0 0 0 1  \* 1 -1 1 -1** -**1 1 -1 -1** -**0 0 0 1  \* 1 1 -1 -1** -**1 -1 -1 -1** -**0 0 0 1  \* 1 -1 -1 -1** -**end** -This indicates that geometrically, the polyhedron has 4 parallel extreme -rays (0,0,t) , one incident to each vertex. With the **geometric** -option, all rays will be printed. Without the option, *lrs* tries to -print each ray once, but in some cases duplicates will remain, see  -subsection Output Duplication. - -**Output Duplication** - -For degenerate inputs, pivot based methods for vertex/ray enumeration -such as *lrs* may generate the same output ray many times. An output is -only printed when it occurs with a lexicographically minimum basis. This -removes all duplicate vertices, but rays may still be output more than -once. This is due to the fact that duplicate geometric rays cannot -always be detected without storing the output. Since V-representations -are automatically lifted to a higher dimension, this will not happen for -facet enumeration. Unless the **allbases** option is specified, *lrs* -makes checks in order to remove duplicates.   A warning message is -produced when duplicates may occur in the output. They can be removed -using the program *buffer.c*. Two important types of input never produce -duplicate output: polytopes (i.e. bounded polyhedra) and cones (i.e. -polyhedra where the origin is the only vertex). - ------------------------------------------------------------------------- - -Acknowledgements and References - -I would like to thank many people for helping with this implementation -project. Komei Fukuda encouraged me from the start, collaborated in -designing the file formats, and provided many suggestions for improving -the code. Debugging would have been almost impossible without the use of -his program cdd as a benchmark. David Bremner implemented memory -allocation, cacheing and signals. Ambros Marzetta demonstrated the -importance of cacheing and lrslong is based on his earlier -implementation of this as prs_single.  Jerry Quinn coded the integer -divide routine. Bug reports were provided by many users, for which I -thank them. In particular Gerardo Garbulsky's extensive use of earlier -versions suggested many refinements and Andreas Enge helped debug the -volume computation. Tallman Nkgau contributed fourier. - -D. Avis, lrs: A Revised Implementation of the Reverse Search Vertex -Enumeration Algorithm, -[http://cgm.cs.mcgill.ca/~avis/doc/avis/Av98a.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98a.ps) -   In: Polytopes - Combinatorics and Computation, Ed. G. Kalai and G. -Ziegler, Birkhauser-Verlag (2000) 177-198. - -D. Avis, "Computational Experience with the Reverse Search Vertex -Enumeration Algorithm," Optimization Methods and Software, (1998 (to -appear)). -[http://cgm.cs.mcgill.ca/~avis/doc/avis/Av98b.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/Av98b.ps) - -D. Avis, D. Bremner, and R. Seidel, "How Good are Convex Hull -Algorithms?," Computational Geometry: Theory and Applications, Vol -7,pp.265-301(1997). -[http://cgm.cs.mcgill.ca/~avis/doc/avis/ABS96a.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/ABS96a.ps) - -D. Avis and L. Devroye, "Estimating the Number of Vertices of a -Polyhedron," pp. 179-190 in Snapshots of Computational and Discrete -Geometry, ed. D. Avis and P. Bose, School of Computer Science, McGill -University (1994). -[http://cgm.cs.mcgill.ca/~avis/doc/avis/AD94a.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AD94a.ps) -  In: Information Processing Letters, (2000) V. 73, pp. 137-143. - -D. Avis and K. Fukuda, "A Pivoting Algorithm for Convex Hulls and Vertex -Enumeration of Arrangements and Polyhedra," Discrete and Computational -Geometry, Vol. 8, pp. 295-313 (1992).  -[http://cgm.cs.mcgill.ca/~avis/doc/avis/AF92b.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AF92b.ps) - -D. Avis, K. Fukuda and S. Picozzi, "On Canonical Representations of -Convex Polyhedra", Mathematical Software,  ICMS 2002, Ed. A. Cohen, X-S -Gao, N. Takayama, World Scientific, pp.350-360 (2002)  - [http://cgm.cs.mcgill.ca/~avis/doc/avis/AFP02a.ps](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/AFP02a.ps) - -D. Avis, G. Rosenberg, R. Savani, B. von Stengel, "Enumeration of Nash -Equilibria for Two-Player Games", Economic Theory 42(2009) 9-37  -[pdf](http://cgm.cs.mcgill.ca/%7Eavis/doc/avis/ARSS09a.pdf) - -D. Bremner, K. Fukuda and A. Marzetta, Primal-Dual Methods for Vertex -and Facet Enumeration, 13th ACM  Symposium on Computational Geometry SCG -1997, 49-56.   - - - - - - diff --git a/apn/lean/docs/msolve/LICENSE b/apn/lean/docs/msolve/LICENSE deleted file mode 100644 index d159169d..00000000 --- a/apn/lean/docs/msolve/LICENSE +++ /dev/null @@ -1,339 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. diff --git a/apn/lean/docs/msolve/msolve-tutorial.txt b/apn/lean/docs/msolve/msolve-tutorial.txt deleted file mode 100644 index c182bfcd..00000000 --- a/apn/lean/docs/msolve/msolve-tutorial.txt +++ /dev/null @@ -1,742 +0,0 @@ - - -1 Introduction -msolve is a C library for solving multivariate polynomial systems of equations. It relies on -computer algebra, a.k.a. symbolic computation, algorithms to compute algebraic representations -of the solution set from which, much, if not all, information can be extracted. - - - - Solving polynomial systems with msolve is global by contrast to local numerical routines. -The use of computer algebra methods allow also the user to bypass classical numerical issues -encountered by numerical methods for polynomial system solving such as those based on -numerical homotopy continuation or semi-definite programming. - msolve relies mainly on Gröbner bases algorithms (see below for a some basic definitions -and properties). It is highly optimized, uses AVX2 vectorization instructions and multi-threading. - It uses the GMP library (handling multi-precision integers) and the FLINT library (handling -arithmetics of univariate polynomials). - msolve can be downloaded from - - https://msolve.lip6.fr - -where binaries (for x86 processors running Linux operating systems) and source files are -provided. - msolve is designed for 64 bit architectures, with AVX2 instructions. - msolve allows you to: - - • isolate all real solutions to polynomial systems with rational coefficients and finitely - many complex solutions; - - • compute Gröbner bases of polynomial systems with coefficients which are either rational - numbers or in a prime field ℤ/𝑝ℤ with 𝑝 < 231 ; - - • compute parametrizations of the solutions of polynomial systems with coefficients which - are either rational numbers or in a prime field ℤ/𝑝ℤ with 𝑝 < 231 (assuming that the - system has finitely many solutions with coordinates in an algebraic closure of the field - generated by the input coefficients). - - msolve is based on Gröbner bases computations. When launching msolve on an input -polynomial system (see the file format in section 2), a Gröbner basis computation starts and -allows msolve to determine if the number of solutions to the system is infinite or finite in an -algebraic closure of the base field (the complex numbers when the input coefficients are rational -numbers). - When the number of solutions is finite, one says that the system (or the ideal generated -by the input equations) has dimension zero at most. Else it has positive dimension. Section 3 -shows how msolve behaves when the input system has positive dimension or when there is -no solution at all in an algebraic closure of the base field (over the complex numbers when the -input coefficients are rational numbers). - When the system has dimension at most zero, msolve can compute the real solutions or, -as said above, compute a Gröbner basis (when the base field is a prime field) or compute a -parametrization of the solutions. Section 4 shows how to use msolve for solving polynomial -systems over the reals when they have dimension at most zero. Section 5 shows how to -use msolve for computing Gröbner bases over prime fields (with some restriction on the - - - - -bit size of the considered prime). Section 6 shows how to use msolve for computing rational -parametrizations of solutions to polynomial systems which have dimension at most zero. Finally, -section 8 summarizes some options which can be used rational parametrizations of solutions to -polynomial systems which have dimension at most zero. Finally, section 8 summarizes some -options which can be used. - The msolve library is described in [1] with implementation details on the algorithms used -therein. All computations performed over the rational numbers (e.g. for computing real roots) are -based on multi-modular computations with a probabilistic stopping criterion. Unless explicitly -requested by the user (see the -l flag in section 8), all computations of Gröbner bases in prime -fields use deterministic algorithms. Change of order algorithms which are used are deterministic -when the input ideal is radical. - - -2 Input file format -msolve allows you to solve polynomial systems either with coefficients which are either rational -numbers or in a prime field ℤ/𝑝ℤ with 𝑝 < 231 . If you aim at solving polynomial systems with -coefficients which are floating point numbers, you can just replace these floating point numbers -with rational numbers. Further, we explain how the input files of msolve should be. - Consider the following polynomial system of equations - 𝑥 + 2𝑦 + 2𝑧 − 1 = 0 - 𝑥 2 + 2𝑦 2 + 2𝑧 2 − 𝑥 - = 0 - 2𝑥𝑦 + 2𝑦𝑧 − 𝑦 = 0 -in ℚ[𝑥, 𝑦, 𝑧]. - In order to solve it with msolve one simply produces a file with the following content - - x,y,z - 0 - x+2*y+2*z-1, - x^2+2*y^2+2*z^2-x, - 2*x*y+2*y*z-y - - - Hence the structure of input files to msolve is as follows: - - 1. the first line contains the variables of the input system, separated with a comma (no - comma at end of line); - - 2. the second line contains the characteristic of the field over which computations are - performed; - - 3. the next lines contain polynomials, in expanded form, separated by a comma and with a - line break (no comma or line break for the last one). - - - - - In each given polynomial, msolve expects a single occurrence of each monomial; if some -monomial appears several times (e.g. as in x+2*y+2*z-x), the behavior of msolve’s parser is -undefined. - When one wants to solve this system over 65521ℤ ℤ - one just replaces 0 by 65521 in the second -line. Note that in the positive characteristic case the coefficients used should be smaller or equal -to 231 − 1. - - x,y,z - 65521 - x+2*y+2*z-1, - x^2+2*y^2+2*z^2-x, - 2*x*y+2*y*z-y - - - - -3 Computing the dimension -To make things explicit on the behavior of msolve when the input system does not have finitely -many complex solutions, let us consider first the example below. - - x, y - 0 - x*y-1, - x - - - Then, msolve outputs - - - [-1]: - - - - indicating that the dimension of the set of complex solutions is −1, hence it is empty. - If now, one considers the following example. - - x, y, z - 0 - x^2-y^2, - x-y - - - Then, msolve outputs - - - - - [1, 3, -1, []]: - - - - The first integer 1 indicates that the complex solution is positive dimensional (note that the -actual dimension of the complex solution set is 2). - - -4 Solving over the reals (finitely many solutions) -The basic functionality msolve allows you to perform is real root isolation for polynomial sys- -tems with rational coefficients and with finitely many complex solutions. This latter requirement -is automatically tested by msolve. - For instance, consider the following input to msolve written in a file in.ms. - - x,y,z - 0 - x+2*y+2*z-1, - x^2+2*y^2+2*z^2-x, - 2*x*y+2*y*z-y - - - Then, typing the following command line - - ./msolve -f in.ms -o out.ms - - - - - will display in the out.ms file the following content. - - [0, [1, - [[[107291359935630315248585097660753910587 / 2^127, 26822839983907578812146274415188477647 / 2^125], [107291359935630315248585097660753910587 / - 2^128, 26822839983907578812146274415188477647 / 2^126], [-355532291286331190123863132844989723573 / 2^131, - -1422129165145324760495452531379958894291 / 2^133]], [[1, 1], [0, 0], [0, 0]], [[38543940173343311950004019810003894311 / 2^127, - 77087880346686623900008039620007788667 / 2^128], [9635985043335827987501004952500973579 / 2^126, 4817992521667913993750502476250486791 - / 2^125], [93053303113782607831679264095876317083 / 2^128, 372213212455130431326717056383505268333 / 2^130]], - [[7089215977519551322153637654828504405 / 2^124, 113427455640312821154458202477256070491 / 2^128], [-1 / 2^127, 1 / 2^127], - [1814839290245005138471331239636097127765 / 2^132, 907419645122502569235665619818048563883 / 2^131]]] - ]]: - - - - - This is a list whose first element is the integer 0 indicating that the input polynomial system -has finitely many complex solutions. The second element of this list is a list which provides the -coordinates of the real solutions as follows: - • the first element is an integer ℓ indicating how many lists are given further; in the above - example, the integer 1 tells that we have a single list (this will be the usual case); - • the next are ℓ lists 𝐿1, . . . , 𝐿ℓ which encode the solutions to the input system; each of them - containing boxes isolating a single real solution. - - - -For instance, from the above output, we deduce that the box defined by - 107291359935630315248585097660753910587 -  -  -  2127 -  107291359935630315248585097660753910587 ⩽ 𝑥 ⩽ 26822839983907578812146274415188477647 - 2125 - , - 26822839983907578812146274415188477647 -  - 2128 - ⩽ 𝑦 ⩽ 2126 - , -  −355532291286331190123863132844989723573 −1422129165145324760495452531379958894291 -  -  -  2131 ⩽ 𝑧 ⩽ 2133 - -contains a single real solution to the input system. - Sometimes, it makes sense to increase the precision. To do that, we use the -p flag, followed -by an integer monitoring the used precision, as follows. - - ./msolve -p 256 -f in.ms -o out.ms - - - - - We obtain in out.ms the following - - [0, [1, - [[[36509357909062631536129668436573070012487487067100583303001175658946635606055 / 2^255, - 4563669738632828942016208554571633751560935883387572912875146957368329450757 / 2^252], - [36509357909062631536129668436573070012487487067100583303001175658946635606055 / 2^256, - 4563669738632828942016208554571633751560935883387572912875146957368329450757 / 2^253], - [-60490684797868661441895377475208744393359927205523538345094237255746825568573 / 2^258, - -483925478382949291535163019801669955146879417644188306760753898045974604548583 / 2^261]], [[1, 1], [0, 0], [0, 0]], - [[3278955798161077339921616998930436909728483733114914607048732943254033559905 / 2^253, - 26231646385288618719372935991443495277827869864919316856389863546032268479285 / 2^256], - [6557911596322154679843233997860873819456967466229829214097465886508067119813 / 2^255, - 13115823192644309359686467995721747638913934932459658428194931773016134239637 / 2^256], - [63328796466738957984825113025800917297614244935801930326677856915848592681411 / 2^257, - 126657592933477915969650226051601834595228489871603860653355713831697185362823 / 2^258]], - [[2412335192444087404657728854347664746943124680534178417488699666831523534165 / 2^252, - 38597363079105398474523661669562635951089994888546854679819194669304376546651 / 2^256], [-1 / 2^255, 1 / 2^255], - [617557809265686375592378586713002175217439918216749674877107114708870024746325 / 2^260, - 308778904632843187796189293356501087608719959108374837438553557354435012373163 / 2^259]]] - ]]: - - - - -5 Computing Gröbner bases -msolve relies on Gröbner bases algorithms which allow one to rewrite the input polynomial -system as an equivalent system which reveals properties of the solution set (dimension, degree) -and to compute “modulo” the input equations. - msolve provides Gröbner bases computations for the so-called grevlex ordering (see e.g. [2]) -when the coefficients either lie in the field of rational numbers or when they lie in the prime -field case. For instance, assume the file in.ms contains the following: - - z1, z2, z3 - 1073741827 - 7*z1*z2+5*z2*z3+z3^2+z1+5*z3+10, - 7*z3^2-27*z1^2-15*z2^2+59*z3+3*z1, - 8*z1^2+13*z1*z3+10*z3^2+z2+z1 - - - - - Now, typing the following command: - - ./msolve -g 2 -f in.ms -o out.ms - - - - - where the -g flag indicates that one aims at computing a Gröbner basis. The value 2 tells -msolve to compute the Gröbner basis for the grevlex order with 𝑧 1 ≻ 𝑧 2 ≻ 𝑧 3 . The computed -Gröbner basis is then printed in the file out.ms as follows. - - #Reduced Groebner basis data - #--- - #field characteristic: 1073741827 - #variable order: z1, z2, z3 - #monomial order: graded reverse lexicographical - #length of basis: 6 elements sorted by increasing leading monomials - #--- - [1*z2^2+832149913*z1^1*z3^1+876889156*z3^2+295279002*z1^1+724775733*z2^1+143165573*z3^1, - 1*z1^1*z2^1+613566759*z2^1*z3^1+766958448*z3^2+766958448*z1^1+613566759*z3^1+153391691, - 1*z1^2+134217730*z1^1*z3^1+268435458*z3^2+671088642*z1^1+671088642*z2^1, - 1*z2^1*z3^2+722232944*z3^3+180778379*z1^1*z3^1+1027531442*z2^1*z3^1+173735741*z3^2+936498976*z1^1+702034498*z2^1+921316952*z3^1+59915395, - 1*z1^1*z3^2+557357968*z3^3+911535897*z1^1*z3^1+419648179*z2^1*z3^1+96648475*z3^2+698659259*z1^1+282295066*z2^1+885328953*z3^1+769127629, - 1*z3^4+250491376*z3^3+716275774*z1^1*z3^1+91652836*z2^1*z3^1+88303466*z3^2+855797860*z1^1+18642214*z2^1+728901227*z3^1+969918485]: - - - - - When one is interested only in the leading monomials of the Gröbner basis (which is a way -smaller output), one simply uses the -g 1 flag as follows - - ./msolve -g 1 -f in.ms -o out.ms - - - - - and we obtain: - - #Leading ideal data - #--- - #field characteristic: 1073741827 - #variable order: z1, z2, z3 - #monomial order: graded reverse lexicographical - #length of basis: 6 elements sorted by increasing leading monomials - #--- - [z2^2, - z1^1*z2^1, - z1^2, - z2^1*z3^2, - z1^1*z3^2, - z3^4]: - - - - - Note that from this list of monomials, one can deduce the Hilbert series of the ideal generated -by the input equations and then its dimension and its degree (see [2]). - Note that when the -g 1 flag is used in characteristic 0, the result is always probabilistic: the -leading monomials are deduced from two computations over a prime field, the first prime being -chosen randomly. - For instance, in the above example, one can deduce that the ideal has dimension 0 (finitely - - - - -many solutions with coordinates in an algebraic closure of 1073741827ℤ - ℤ - ) since the basis of leading -monomials contain pure powers of all variables. The degree of the ideal is also 8 since there are -8 monomials in 𝑧 1, 𝑧 2, 𝑧 3 which are not divisible by the above leading monomials. - msolve also allows you to perform Gröbner bases computations using one-block elimination -monomial order thanks to the -e flag. The following command - - ./msolve -e 1 -g 2 -f in.ms -o out.ms - - - - - on - - t, w, x, y, z - 1073741827 - w^4, - x^4, - w*y^3+1073741826*x*z^3, - t*z+1073741826 - - - will perform the Gröbner basis computation eliminating the first variable. The output is - - #Reduced Groebner basis data - #--- - #field characteristic: 1073741827 - #variable order: t, w, x, y, z - #monomial order: eliminating first variable, blocks: graded reverse lexicographical - #length of basis: 7 elements sorted by increasing leading monomials - #--- - [1*w^1*y^3+1073741826*x^1*z^3, - 1*x^4, - 1*w^1*x^3, - 1*w^2*x^2, - 1*w^3*x^1, - 1*w^4, - 1*t^1*z^1+1073741826]: - - - - - where we see that the first 6 polynomials are only in 𝑤, 𝑥, 𝑦, 𝑧, which corresponds to the -elimination of the variable 𝑡. When the input coefficients lie in the field of rational numbers -(hence, characteristic 0), the returned Gröbner basis is the one of the elimination ideal, i.e. they -have partial degree 0 in the variables to eliminate. - More generally, using -e k will eliminate the 𝑘 first variables. Thus, - - ./msolve -e 2 -g 2 -f in.ms -o out.ms - - - - - will eliminate 𝑡 and 𝑤, yielding - - - - - #Reduced Groebner basis data - #--- - #field characteristic: 1073741827 - #variable order: t, w, x, y, z - #monomial order: eliminating first 2 variables, blocks: graded reverse lexicographical - #length of basis: 7 elements sorted by increasing leading monomials - #--- - [1*x^4, - 1*w^1*y^3+1073741826*x^1*z^3, - 1*w^1*x^3, - 1*t^1*z^1+1073741826, - 1*w^2*x^2, - 1*w^3*x^1, - 1*w^4]: - #Reduced Groebner basis for input in characteristic 1073741827 - #for variable order t, w, x, y, z - #w.r.t. grevlex monomial ordering - #consisting of 7 elements: - [1*x^4, - 1*w^1*y^3+1073741826*x^1*z^3, - 1*w^1*x^3, - 1*t^1*z^1+1073741826, - 1*w^2*x^2, - 1*w^3*x^1, - 1*w^4]: - - - - - where we see that only the first polynomial is not in 𝑡 and 𝑤. - - -6 Parametrizations of (finitely many) solutions -Assume that the input polynomials have coefficients in some field 𝕂 with variables 𝑥 1, . . . , 𝑥𝑛 . In -the case of polynomial systems of dimension 0, msolve computes by default a zero-dimensional -parametrization of the solution set. The user can obtain such an encoding using the -P flag (see -below). - Let us recall what a rational parametrization is. This is a couple (P, ℓ) where ℓ is a linear form -𝜆1𝑥 1 + · · · + 𝜆𝑛 𝑥𝑛 with 𝜆𝑖 ∈ 𝕂 (for 1 ⩽ 𝑖 ⩽ 𝑛), P is a sequence of polynomials (𝑤, 𝑤 ′, 𝑣 1, . . . , 𝑣𝑛 ) -in 𝕂 [𝑡] where 𝑡 is a new variable such that: - • when 𝕂 is a prime field, 𝑤 ′ = 1 else 𝑤 ′ = 𝜕𝑤 - 𝜕𝑡 ; - - • deg(𝑣𝑖 ) < deg(𝑤) for 1 ⩽ 𝑖 ⩽ 𝑛; - - • 𝜆1𝑣 1 + · · · + 𝜆𝑛 𝑣𝑛 = 𝑡𝑤 ′ mod 𝑤 -and the solution set to the input polynomials coincides with the set: -    - 𝑣 1 (𝜗) 𝑣𝑛 (𝜗) - − ′ ,...,− ′ 𝑤 (𝜗) = 0 . - 𝑤 (𝜗) 𝑤 (𝜗) -In algebraic words, the polynomials 𝑤 ′𝑥𝑖 + 𝑣𝑖 belong to the radical of the ideal generated by the -input equations and the form 𝜆1𝑥 1 + · · · + 𝜆𝑛 𝑥𝑛 + 𝑡. - msolve outputs univariate polynomials as an array [deg,L] where deg is the degree of the -polynomial under consideration and L is the array of its coefficients in the monomial basis -by increasing degree and c is a denominator to all coefficients. For instance, the polynomial -𝑥 2 + 3𝑥 − 2 is encoded by - - - -[2, [-2, 3, 1]] - - We first explain msolve’s output in the case where the input coefficients are rational numbers -(the characteristic zero case). For an input in the file in.ms - - z1, z2 - 0 - z1^2+z2^2-1, - z1^2-z2^2 - - - the command - - ./msolve -P 2 -f in.ms - - - - - msolve outputs is - - [0, [0, - 3, - 4, - [’z1’, ’z2’, ’A’], - [-119/576,69/576,5/576], - [1, - [[4, [883600, 0, -18922, 0, 25]], - [3, [0, -37844, 0, 100]], - [ - [[3, [223720, 0, -1190, 0]], - 1], - [[3, [129720, 0, 690, 0]], - 1] - ]]]]]: - - - - - and has the following structure - - [0, [0, nvars, deg, vars, form, [1,[lw, lwp, param]]]]: - - - - - where - • the first 0 indicates that the input system has finitely many complex solutions (dimension - at most 0); - - • the second 0 is the characteristic; - - • nvars is the number of variables used for the parametrization (it coincides with the - number of input variables if the form ℓ is chosen as one of the variables else it is one - more); - - • deg is the number of solutions, counted with multiplicities (in other words the degree of - the ideal generated by the input equations); - - - - • vars is the list of variables following the ordering used for computing the parametrization - (hence, with maybe with one more variable than the ones given as input). - In our example, msolve outputs: - [’z1’, ’z2’, ’A’] - - where A is a new variable. - - • form is the list of coefficients for the linear form ℓ when it does not coincide with one of - the input variables (else it is an empty list); - In our example, this is a list of three rational numbers, say [-119/576,69/576,5/576], - indicating that the linear form used to compute the rational parametrization is - -119/576*z1+69/576*z2+5/576*A - - • the next 1 indicates that a single parametrization is returned next (the one encoded by - [lw, lwp, param]); - - • lw is the encoding of the eliminating polynomial 𝑤; - - • lwp is the encoding of the denominator used in the rational parametrization; - - • param is the list of the output parametrizations, there are 𝑛 − 1 where 𝑛 is the number of - elements in vars ; they are encoded as follows [[deg, L], c] where c is an integer which - divides the polynomial encoded by [deg, L]. - The first one corresponds to the first variable in vars, the second parametrization cor- - responds to the second variable in vars and so on. Hence, the variable which is used to - parametrize the solution set is always the last one. - -We illustrate now how the output looks like on input file in.ms - - z1, z2, z3 - 0 - z1^2-z2^2+z3^2-4, - z1*z2+2*z2*z3-3*z3*z1-1, - z1+2*z2+3*z3-1 - - - Using ./msolve -P 2 -f in.ms the output is - - - - - [0, [0, - 3, - 4, - [’z1’, ’z2’, ’z3’], - [0, 0, 1], - [1, - [[4, [-116, -210, 1484, -344, 53]], - [3, [-210, 2968, -1032, 212]], - [ - [[3, [1894, 162, -1636, 192]], - 1], - [[3, [-146, -620, -3118, 314]], - 1] - ]]]]]: - - - - - On this example, all variables are parametrized by the variable z3. - The polynomial 𝑤 is −116 − 210𝑧 3 + 1484𝑧 32 − 344𝑧 33 + 53𝑧 34 . The polynomials 𝑣 1 and 𝑣 2 are -respectively - 𝑣 1 = 1894 + 162𝑧 3 − 1636𝑧 32 + 192𝑧 33 and 𝑣 2 = −146 − 620𝑧 3 − 3118𝑧 32 + 314𝑧 33 . -Note that we can get both the parametrization and the real roots. For instance, using the -command ./msolve -P 1 -f in.ms, one obtains - - [0, [0, - 3, - 4, - [’z1’, ’z2’, ’z3’], - [0, 0, 1], - [1, - [[4, [-116, -210, 1484, -344, 53]], - [3, [-210, 2968, -1032, 212]], - [ - [[3, [1894, 162, -1636, 192]], - 1], - [[3, [-146, -620, -3118, 314]], - 1] - ]]]],[1, - [[[679375673646273705027530285330331715009 / 2^128, 339687836823136852513765142665165857505 / 2^127], [-60535166785954698124918883091179878673 - / 2^128, -3783447924122168632807430193198742417 / 2^124], [-1162789190151604508343028862486419979779 / 2^132, - -581394595075802254171514431243209989889 / 2^131]], [[-756665306660103909967296571629791504137 / 2^128, - -756665306660103909967296571629791504135 / 2^128], [88745898258177294078528671940999802399 / 2^126, - 177491796516354588157057343881999604799 / 2^127], [2063895933416661444279689618845660247455 / 2^132, - 4127791866833322888559379237691320494911 / 2^133]]] - ]]: - - - - - We end this section with the same example as above but seeing the coefficients in ℤ/65521ℤ. - - z1, z2, z3 - 65521 - z1^2-z2^2+z3^2-4, - z1*z2+2*z2*z3-3*z3*z1-1, - z1+2*z2+3*z3-1 - - - The call ./msolve -P 2 -f in.ms then outputs - - - - - [0, [65521, - 3, - 4, - [’z1’, ’z2’, ’z3’], - [0, 0, 1], - [1, - [[4, - [16069, 9886, 28, 2466, 1]], - [0, - [1]], - [ - [[3, - [6276, 37054, 57744, 4959]]], - [[3, - [29622, 14235, 36649, 30281]]] - ]]]]]: - - - - -7 Saturation and colon ideals -msolve also proposes algorithms for computing Gröbner bases of saturation and colon ideals. -Given 𝑚 + 1 polynomials 𝑓1, . . . , 𝑓𝑚 , 𝜑 over a field 𝕂 with variables 𝑥 1, . . . , 𝑥𝑛 , the saturation -ideal ⟨𝑓1, . . . , 𝑓𝑚 ⟩ : ⟨𝜑⟩ ∞ is the ideal of all polynomials ℎ, such that there exists 𝑘 ∈ ℕ such that -ℎ𝜑 𝑘 ∈ ⟨𝑓1, . . . , 𝑓𝑚 ⟩. The colon ideal ⟨𝑓1, . . . , 𝑓𝑚 ⟩ : ⟨𝜑⟩ is the ideal of all polynomials ℎ, such that -ℎ𝜑 ∈ ⟨𝑓1, . . . , 𝑓𝑚 ⟩. - A Gröbner basis for the grevlex order can be computed in the former case with an input file -containing 𝑓1, . . . , 𝑓𝑚 , 𝜑 and called with the flag -S to use the F4SAT algorithm. Note that this -option is at the moment restricted to 32 bit prime fields. - For instance, consider the following input to msolve written in a file in.ms. - - w, x, y, z - 1073741827 - w^4, - x^4, - 1073741826*x*z^3+w*y^3, - z - - - Then, typing the following command line - - ./msolve -S -g 2 -f in.ms -o out.ms - - - - - will display in the out.ms file the following content. - - - - - #Reduced Groebner basis data - #--- - #field characteristic: 1073741827 - #variable order: w, x, y, z - #monomial order: graded reverse lexicographical - #length of basis: 6 elements sorted by increasing leading monomials - #--- - [1*w^1*y^3+1073741826*x^1*z^3, - 1*x^4, - 1*w^1*x^3, - 1*w^2*x^2, - 1*w^3*x^1, - 1*w^4]: - - - - -8 More flags and options - • The flag -h or --help displays some documentation - - • The flag -v or --verbose controls the verbosity - Default value: 0 - - • The flag -t or --threads controls the number of threads used - Default value: 1 - - • The flag -p or --precision controls the binary precision of the output of - the univariate real root solver (default value may be automatically increased by msolve - when needed). - Default value:128 - - • The flag -g or --groebner-basis tells msolve to output the leading monomial of - the ideal generated by the input polynomials (when is 1) or the minimal reduced - Gröbner basis (when is 2 and a prime characteristic is indicated). - Default value:0 - - • The flag -P or --precision tells msolve to output the rational parametriza- - tion computed for solving zero-dimensional polynomial systems (those with finitely many - solutions in an algebraic closure of the base field). When -P 0 is set, such a parametrization - is not returned, when -P 1 is set, the parametrization is returned and, in the characteristic - zero case (rational coefficients), real solutions are returned, when -P 2 is set, only the - rational parametrization is returned. - Default value:0 - - • The flag -c tells msolve how to handle genericity requirements: when is - 0 msolve quits when these requirements are not satisfied, when is 1 msolve is - allowed to change the order of the variables if needed and quits if after these changes, the - genericity requirements are not satisfied, when is 2 msolve is allowed to introduce - - - - a new variable and a linear form until the genericity requirements are satisfied. In - positive characteristic, this linear have random coefficients, while in characteristic 0, it is - deterministically chosen, depending on the input. - Default value:2 - - • The flag -d tells msolve how to handle further genericity requirements when the - staircase is not generic enough by computing some normal forms: can go from 0 - (no normal form computations are computed) to 4 (all the normal forms are computed). - Default value:2 - - • The flag --random-seed tells msolve which seed must be used to initialize the - pseudo-random generator: -1 means that time(0) is used so that the seed is based on - current time, otherwise, for any nonnegative integer N, N will be the seed. The latter - option is for debug purpose only as the lack of randomization can lead to failures on some - input. - Default value:0 - - - diff --git a/apn/lean/docs/nauty/COPYRIGHT b/apn/lean/docs/nauty/COPYRIGHT deleted file mode 100644 index d826b92a..00000000 --- a/apn/lean/docs/nauty/COPYRIGHT +++ /dev/null @@ -1,44 +0,0 @@ -This is the license for the software package Nauty and -Traces, package versions 2.6r3 and later. - -Five categories of software are included in the package: -A. All files not listed as B-G below, copyright Brendan McKay (1984-) -B. Files traces.h, traces.c and dretodot.c, copyright Adolfo Piperno (2008-) -C. File watercluster2.c and genposetg.c, copyright Gunnar Brinkmann (2009-) -D. Files planarity.h and planarity.c, copyright Magma project. -E. Files nautycliquer.h and nautycliquer.c, copyright to Sampo - Niskanen and Patric Östergård. -F. Much of file nauchromatic.c, copyright Gordon Royle. -G. The code in nausha.c was put into the public domain by Brad Conte. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this software except in compliance with the License. -A copy of the License is included in the package and can also -be viewed at - - https://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - -Brendan McKay: Australian National University; Brendan.McKay@anu.edu.au -Adolfo Piperno: University of Rome "Sapienza"; piperno@di.uniroma1.it -Gunnar Brinkmann: University of Ghent; Gunnar.Brinkmann@UGent.be -Magma Administration: University of Sydney; admin@maths.usyd.edu.au -Patric Ostergard: Aalto Univerity; patric.ostergard@aalto.fi - ----END-OF-FORMAL-COPYRIGHT-NOTICE--- - -Earlier (pre-2.6) versions of this package carried a different -notice: "Permission is hereby given for use and/or distribution -with the exception of sale for profit or application with nontrivial -military significance." These days most people use nauty via a -larger package such as Magma, Sage, or GAP, and often they don't -even know they are using nauty. Due to the legal nonsense that -large package distributors need to worry about, it has proved too -much trouble to maintain an idiosyncratic licence. I didn't change -my opinion about military use, but it is no longer part of the -formal notice. Brendan McKay (Jan 20, 2016) diff --git a/apn/lean/docs/nauty/LICENSE b/apn/lean/docs/nauty/LICENSE deleted file mode 100644 index d6456956..00000000 --- a/apn/lean/docs/nauty/LICENSE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/apn/lean/docs/nauty/nauty-guide.txt b/apn/lean/docs/nauty/nauty-guide.txt deleted file mode 100644 index eac5f3fa..00000000 --- a/apn/lean/docs/nauty/nauty-guide.txt +++ /dev/null @@ -1,2039 +0,0 @@ - - -15 Utilities -The nauty package includes a suite of programs called gtools that provide efficient -processing of files of graphs stored in graph6, sparse6 or digraph6 format. These formats -are defined in Section 20. - Most of the gtools programs will run on any system with a modern C compiler, but -a few need Unix-like facilities. For example, the program shortg requires a program -compatible with the Unix sort program, as well as the popen system routine. - A general principle is that data is sent to stdout (unless an alternative output file is -named) and diagnostic output is sent to stderr. - All the gtools programs are self-documenting: just execute with the option --help -to see an explanation of all the features. We only list the basic functions of the programs -here; see Section 24 for more details. - -addedgeg : add an edge in each possible way -addptg : add extra vertices in various ways -amtog : read graphs in adjacency matrix form -ancestorg : remove some final vertices from graphs -assembleg : form graphs whose components are input graphs -biplabg : label bipartite graphs so the colour classes are contiguous -catg : concatenate files of graphs -complg : complement graphs -converseg : converse digraphs -copyg : convert format and select subset -countg : count graphs according to a variety of properties -cubhamg : find hamiltonian cycles in subcubic graphs -deledgeg : delete an edge in each possible way -delptg : delete some vertices in each possible way -dimacs2g : read files of graphs in DIMACS format -directg : generate small digraphs with given underlying graph -dretodot : read graphs in dreadnaut form and write in dot format for drawing -dretog : read graphs in dreadnaut form -edgetransg : select by group action on vertices, edges and arcs -genbg : generate small bicoloured graphs - -geng : generate small graphs -genposetg : generate posets -genquartic : generate quartic graphs -genrang : generate random graphs -genspecialg : generate special graphs, like cycles and complete graphs -gentourng : generate small tournaments -gentreeg : generate trees -genktreeg : generate k-trees -hamheuristic : try to find hamiltonian cycles in any graphs, without guaranteed success -labelg : canonically label graphs -linegraphg : make the linegraphs of a file of graphs -listg : display graphs in a variety of forms -multig : generate small multigraphs with given underlying graph -newedgeg : in each possible way, subdivide two non-adjacent edges and join the two new - vertices -nbrhoodg : extract neighbourhood graphs -newedgeg : subdivide non-adjacent edges and join the new vertices -NRswitch : switch the edges between the neighbourhood and the complementary neigh- - bourhood, for each vertex -pickg : select graphs according to a variety of properties -planarg : test graphs for planarity and find embeddings or obstructions. -productg : make product of two graphs -ranlabg : randomly relabel graphs -ransubg : random subgraph or orientation -shortg : remove isomorphs from a file of graphs -showg : a stand-alone limited subset of listg -subdivideg : make the subdivision graphs of a file of graphs -twohamg : split quartic graphs into two hamiltonian cycles -underlyingg : undirected graph underlying directed graph -uniqg : select non-isomorphic graphs -vcolg : colour the vertices of graphs in all distinct ways -watercluster2 : an alternative to directg which is usually faster - - Further programs will be added. Requests are welcome. - - -19 Advanced geng usage -Several of the programs have the facility to compile user code into them in a way that -influences their behaviour. The technical details are described inside the source code of -those programs, For example, if P is a graph property that is preserved on removing a -vertex (such as absence of a particular subgraph), then geng can generate graphs with that -property more efficiently than filtering at the end. An example is in the file no4holes.c. -/* This is a demonstration plugin for geng. Its function is to remove - graphs containing an induced cycle of length 4. -A typical compilation command would be - gcc -o no4holes -DMAXN=WORDSIZE -O3 -march=native -DPRUNE=no4holes \ - geng.c no4holes.c nauty1.a - -PREPRUNE could be used in place of PRUNE -- adopt whichever is fastest. -The resulting executable will have all the features of geng but also graphs -with induced cycles of length 4 will be excluded. */ - -#include "gtools.h" - -int -no4holes(graph *g, int n, int maxn) -/* n is the size of the current graph and maxn is the output size. The most - recent vertex added was vertex n-1 and the graph without that vertex has - already been tested. So all we need to do is look for induced cycles of - length 4 which include vertex n-1. If we find one, we return 1 to make sure - this graph and its descendants are not output. Otherwise, we return 0. - Note that graphs generated by geng have at most WORDSIZE vertices, and - so we can use a single setword to hold a set of vertices. */ -{ - setword x,y,z; - int i,j; - - x = g[n-1]; /* Neighbours of n-1 */ - while (x) - { - TAKEBIT(i,x); /* i is next neighbour; remove it from x */ - y = x & ~g[i]; /* Later neighbours of n-1, not adjacent to i */ - z = g[i] & ~g[n-1] & ~bit[n-1]; /* Neighbours of i that are - non-neighbours of n-1 */ - while (y) - { - TAKEBIT(j,y); /* Second neighbour of n-1 */ - if ((g[j] & z)) return 1; /* Found 4-hole */ - } - } - return 0; -} - -20 Graph formats used by the utilities - -This is the file formats.txt. - - -Description of graph6, sparse6 and digraph6 encodings ------------------------------------------------------ -Brendan McKay, brendan.mckay@anu.edu.au -Updated Jun 2015, Apr 2022, Aug 2023. - -General principles: - - All numbers in this description are in decimal unless obviously - in binary. - - The character code used in all cases is ASCII, but no bytes are - present which would cause ambiguity if the file is read as UTF8. - - Apart from the header, there is one object per line. Apart from - the header, end-of-line characters, and the characters ":", ";" - and "&" which might start a line, all bytes have a value in the - range 63-126 (which are all printable ASCII characters). A file of - objects is a text file, so whatever end-of-line convention is - locally used is fine; however the C library input routines must - show the standard single-LF end of line to programs). - -Bit vectors: - - A bit vector x of length k can be represented as follows. - Example: 1000101100011100 - - (1) Pad on the right with 0 to make the length a multiple of 6. - Example: 100010110001110000 - - (2) Split into groups of 6 bits each. - Example: 100010 110001 110000 - - (3) Add 63 to each group, considering them as bigendian binary numbers. - Example: 97 112 111 - - These values are then stored one per byte. - So, the number of bytes is ceiling(k/6). - - Let R(x) denote this representation of x as a string of bytes. - -Small nonnegative integers: - - - Let n be an integer in the range 0-68719476735 (2^36-1). - - If 0 <= n <= 62, define N(n) to be the single byte n+63. - If 63 <= n <= 258047, define N(n) to be the four bytes - 126 R(x), where x is the bigendian 18-bit binary form of n. - If 258048 <= n <= 68719476735, define N(n) to be the eight bytes - 126 126 R(x), where x is the bigendian 36-bit binary form of n. - - Examples: N(30) = 93 - N(12345) = N(000011 000000 111001) = 126 66 63 120 - N(460175067) = N(000000 011011 011011 011011 011011 011011) - = 126 126 63 90 90 90 90 90 - - -Description of graph6 format. ----------------------------- - -Data type: - simple undirected graphs of order 0 to 68719476735. - -Optional Header: - >>graph6<< (without end of line!) - -File name extension: - .g6 - -One graph: - Suppose G has n vertices. Write the upper triangle of the adjacency - matrix of G as a bit vector x of length n(n-1)/2, using the ordering - (0,1),(0,2),(1,2),(0,3),(1,3),(2,3),...,(n-2,n-1). - - Then the graph is represented as N(n) R(x). - -Example: - Suppose n=5 and G has edges 0-2, 0-4, 1-3 and 3-4. - - x = 0 10 010 1001 - - Then N(n) = 68 and R(x) = R(010010 100100) = 81 99. - So, the graph is 68 81 99. - - -Description of sparse6 format. ------------------------------- - -Data type: - Undirected graphs of order 0 to 68719476735. - Loops and multiple edges are permitted. - - - (However, as of May 2022, the utilities in the nauty package - and nauty itself do not support multiple edges and some - utilities do not support loops either.) - -Optional Header: - >>sparse6<< (without end of line!) - -File name extension: - .s6 - -General structure: - - Each graph occupies one text line. Except for the first character - and end-of-line characters, each byte has the form 63+x, where - 0 <= x <= 63. The byte encodes the six bits of x. - - The encoded graph consists of: - (1) The character ’:’. (This is present to distinguish - the code from graph6 format.) - (2) The number of vertices. - (3) A list of edges. - (4) end-of-line - - Loops and multiple edges are supported, but not directed edges. - -Number of vertices n: - - 1, 4, or 8 bytes N(n) as above. - This is the same as graph6 format. - -List of edges: - - Let k be the number of bits needed to represent n-1 in binary. - - The remaining bytes encode a sequence - - b[0] x[0] b[1] x[1] b[2] x[2] ... b[m] x[m] - - Each b[i] occupies 1 bit, and each x[i] occupies k bits. - Pack them together in bigendian order, and pad up to a - multiple of 6 as follows: - 1. If (n,k) = (2,1), (4,2), (8,3) or (16,4), and vertex - n-2 has an edge but n-1 doesn’t have an edge, and - there are k+1 or more bits to pad, then pad with one - 0-bit and enough 1-bits to complete the multiple of 6. - 2. Otherwise, pad with enough 1-bits to complete the - multiple of 6. - These rules are to match the gtools procedures, and to avoid - - - the padding from looking like an extra loop in unusual cases. - - Then represent this bit-stream 6 bits per byte as indicated above. - - The vertices of the graph are 0..n-1. - The edges encoded by this sequence are determined thus: - - v = 0 - for i from 0 to m do - if b[i] = 1 then v = v+1 endif; - if x[i] > v then v = x[i] else output {x[i],v} endif - endfor - - In decoding, an incomplete (b,x) pair at the end is discarded. - -Example: - - :Fa@x^ - - ’:’ indicates sparse6 format. - Subtract 63 from the other bytes and write them in binary, - six bits each. - - 000111 100010 000001 111001 011111 - - The first byte is not 63, so it is n. n=7 - n-1 needs 3 bits (k=3). Write the other bits in groups - of 1 and k: - - 1 000 1 000 0 001 1 110 0 101 1 111 - - This is the b/x sequence 1,0 1,0 0,1 1,6 0,5 1,7. - The 1,7 at the end is just padding. - The remaining parts give the edges 0-1 0-2 1-2 5-6. - - -Description of incremental sparse6 format. ------------------------------------------ - - This is an extension to sparse6 format that is very efficient if most - graphs in a file are similar to the previous graph. - - Each graph occupies one text line. Except for the first character - and end-of-line characters, each byte has the form 63+x, where - 0 <= x <= 63. The byte encodes the six bits of x. - - The encoded graph consists of: - (1) The character ’;’. - - - (2) A list of edges. - (3) end-of-line - - This cannot appear as the first graph in a file. The number of vertices - is taken to be equal to the number of vertices in the previous graph. - The list of edges specifies the symmetric difference of this graph and - the previous graph. It is encoded exactly the same as part (3) of - sparse6 format. - - Loops are supported, but not multiple edges. - - -Description of digraph6 format. ------------------------------- - -Data type: - simple directed graphs (allowing loops) of order 0 to 68719476735. - -Optional Header: - >>digraph6<< (without end of line!) - -File name extension: - .d6 - -One graph: - Suppose G has n vertices. Write the adjacency matrix of G - as a bit vector x of length n^2, row by row. - - Then the graph is represented as ’&’ N(n) R(x). - The character ’&’ (decimal 38) appears as the first character. - -Example: - Suppose n=5 and G has edges 0->2, 0->4, 3->1 and 3->4. - - x = 00101 00000 00000 01001 00000 - - Then N(n) = 68 and - R(x) = R(00101 00000 00000 01001 00000) = 73 63 65 79 63. - So, the graph is 38 68 73 63 65 79 63. - -Note: - SageMath has a format also called "digraph6" that is different - from this one. The leading "&" is omitted and the direction of - every edge is reversed. - - - For a description of the planarcode and edgecode formats, see the plantri docu- -mentation at https://users.cecs.anu.edu.au/∼bdm/plantri/. - -24 Help texts for the utilities - -===== addedgeg ====================================================== - -Usage: addedgeg [-lq] [-D#] [-btfF] [-z#] [infile [outfile]] - -For each edge nonedge e, output G+e if it satisfies certain conditions - - The output file has a header if and only if the input file does. - - -l Canonically label outputs - -D# Specify an upper bound on the maximum degree of the output - -b Output has no new cycles of odd length - -t Output has no new 3-cycle if input doesn’t - -f Output has no new 4-cycle if input doesn’t - -F Output has no new 5-cycle if input doesn’t - -z# Output has no new cycles of length less than # - -btfFz can be used in arbitrary combinations - -q Suppress auxiliary information - -===== addptg ====================================================== - -Usage: addptg [-lq] [-n#] [-j#:#] [-e#:#] [-ck] [-io] [infile [outfile]] - -Add a specified number of new vertices - - The output file has a header if and only if the input file does. - - -l canonically label outputs - -c join each new vertex to all the old vertices - -k make a clique on the set of new vertices - -n# the number of new vertices (default 1) - -j# -j#:# join a new vertex to # old vertices in all possible ways - -e# -e#:# use all joins that give the new graphs # edges - (-j, -e, -D are each incompatible with -n) - -D# upper bound on the maximum (out)degree of the output graphs - -i for a digraph, edges go towards the old vertices - -o for a digraph, edges go away from the old vertices - (-i is the default if neither -i nor -o is given) - -q Suppress auxiliary information - - - - -===== amtog ====================================================== - -Usage: amtog [-n#sgzhq] [-o#] [infile [outfile]] - -Read graphs in matrix format. - - -n# Set the initial graph order to # (no default). - This can be overridden in the input. - -g Write the output in graph6 format (default). - -s Write the output in sparse6 format. - -z Write the output in digraph6 format. - -h Write a header (according to -g or -s). - -w Don’t warn about loops (which are suppressed for -g) - -q Suppress auxiliary information. - -o# Treat digit # as 1 and other digits as 0. - - Input consists of a sequence of commands restricted to: - - n=# set number of vertices (no default) - The = is optional. - m Matrix to follow - An ’m’ is also assumed if a digit is encountered. - M Complement of matrix to follow (as m) - t Upper triangle of matrix to follow, row by row - excluding the diagonal. - T Complement of upper trangle to follow (as t) - s Upper triangle of matrix to follow, row by row - excluding the diagonal; lower triangle is complement. - q exit (optional) - -===== ancestorg ====================================================== - -Usage: ancestorg [-q] [-g#:#|-g#] [infile [outfile]] - -The g-th generation ancestor of a graph is the graph obtained by removing - the final g vertices. The 0-th generation ancestor is the graph itself. - For each input graph, write the ancestors whose generation is given by the - g argument. No zero-sized graphs are written. - Output is always in graph6 format. - - The output file has a header if and only if the input file does. - - -g# -g#:# Specify a generation or range of generations (default: all) - -q Suppress auxiliary information - - - - -===== assembleg ====================================================== - -Usage: assembleg -n#|-n#:# [-i#|i#:#] [-k#|k#:#] [-L] [-q] [-c] [infile [outfile]] - -Assemble input graphs as components of output graphs. - - The output file has no header. - If the input has any directed graphs, all outputs are directed. - Otherwise, the output format is determined by the header - or first input. - The input graphs had better all fit into memory at once, - unless -L is given, in which case only the graphs of at - most half the output size are stored at once. - The output graphs will be non-isomorphic if the input - graphs are connected and non-isomorphic. - - -n# -n#:# Give range of output sizes (compulsory) - -i# -i#:# Give range of input sizes to use - -k# -k#:# How many input graphs to combine (default -k2:) - -L Assume all input graphs strictly larger than maxn/2 - vertices follow any smaller graphs in the input, - where maxn is the largest size specified by -n. - This can greatly reduce memory consumption. - -c Also write graphs consisting of a single input - (equivalent to -k1:, overridden by -k) - -u Generate the graphs but don’t write them - -q Suppress auxiliary information. - -===== biplabg ====================================================== - -Usage: biplabg [-q] [infile [outfile]] - -Label bipartite graphs so that the colour classes are contiguous. - The first vertex of each component is assigned the first colour. - Vertices in each colour class have the same relative order as before. - Non-bipartite graphs are rejected. - - The output file has a header if and only if the input file does. - - -q Suppress auxiliary information. - -===== catg ====================================================== - -Usage: catg [-xv] [infile]... - - Copy files to stdout with all but the first header removed. - - -x Don’t write a header. - - - In the absence of -x, a header is written if - there is one in the first input file. - - -v Summarize to stderr. - -===== complg ====================================================== - -Usage: complg [-lq] [-a] [-L] [-r|-R] [infile [outfile]] - -Take the complements of a file of graphs. - - The output file has a header if and only if the input file does. - The output format is defined by the header or first graph. - - -r Only complement if the complement has fewer directed edges. - -R Only complement if the complement has fewer directed edges - or has the same number of directed edges and is canonically - less than the original. - -a Also output the input graph (before the complement). - -L Complement the loops too. By default, preserve them. - -l Canonically label outputs. - -q Suppress auxiliary information. - -===== converseg ====================================================== - -Usage: converseg [-q] [-a|-c] [infile [outfile]] - -Take the converse digraphs of a file of directed graphs. - - The output file has a header if and only if the input file does. - Undirected graphs are passed through without change, while - directed graphs are written in digraph6 format. - - -a Also output the original graph (before the converse) - -c Output only self-converse digraphs - - -q Suppress auxiliary information. - -===== copyg ====================================================== - -Usage: copyg [-gszfp#:#qhx] [infile [outfile]] - - Copy a file of graphs with possible format conversion. - - -g Use graph6 format for output - -s Use sparse6 format for output - -z Use digraph6 format for output - -i Use incremental sparse6 format for output - - - In the absence of -g, -s, -z or -i, the format - depends on the header or, if none, the first input line. - As an exception, digraphs are always written in digraph6. - - -p# -p#:# - Specify range of input lines (first is 1) - This can fail if the input has incremental lines. - -f With -p, assume input lines of fixed length - (ignored if header or first line has sparse6 format). - -I# Have at most this number of incremental steps - in a row. Implies -i. - - -h Write a header. - -x Don’t write a header. - In the absence of -h and -x, a header is written if - there is one in the input. - - -q Suppress auxiliary output. - -===== countg ====================================================== - -Usage: [pickg|countg] [-fp#:#q -V -X] [--keys] [-constraints -v] [ifile [ofile]] - -countg : Count graphs according to their properties. - pickg : Select graphs according to their properties. - - ifile, ofile : Input and output files. - ’-’ and missing names imply stdin and stdout. - - Miscellaneous switches: - -p# -p#:# Specify range of input lines (first is 1) - May fail if input is incremental. - -f With -p, assume input lines of fixed length - (only used with a file in graph6/digraph6 format) - -v Negate all constraints (but not -p) - -X Reverse selection (but -p still observed) - -V List properties of every input matching constraints. - -l Put a blank line whenever the first parameter changes, - if there are at least two parameters. - -1 Write output as lines of numbers separated by spaces, - with 0/1 for boolean and both endpoints of ranges given - separately even if they are the same, and the count at - the end of the line. Also, no total is written. - -2 The same as -1 but counts are not written. - -9 Flush the output after each graph (expensive if many graphs) - -q Suppress informative output. - - Constraints: - - - Numerical constraints (shown here with following #) can take - a single integer value, or a range like #:#, #:, or :#. Each - can also be preceded by ’~’, which negates it. (For example, - -~D2:4 will match any maximum degree which is _not_ 2, 3, or 4.) - Constraints are applied to all input graphs, and only those - which match all constraints are counted or selected. - - -n# number of vertices -e# number of edges - -ee# number of non-edges (including loops for digraphs) - -L# number of loops -C strongly connected - -LL# number of 2-cycles -cc# number of components - -d# minimum (out-)degree -D# maximum (out-)degree - -m# vertices of min (out-)degree -M# vertices of max (out-)degree - -u# minimum (in-)degree -U# maximum (in-)degree - -s# vertices of min (in-)degree -S# vertices of max (in-)degree - -r regular -b bipartite - -z# radius -Z# diameter - -g# girth (0=acyclic) -Y# total number of cycles - -h# maximum independent set -k# maximum clique - -T# number of triangles -K# number of maximal cliques - -TT# number independent 3-sets -P# number of 5-cycles - -B# smallest possible first side of a bipartition (0 if nonbipartite) - -H# number of induced cycles -W# number of 4-cycles - -E Eulerian (all degrees are even, connectivity not required) - -a# group size -o# orbits -F# fixed points -t vertex-transitive - -O# number of orbits of edges -OO# number of orbits of arcs - -tt# 1 = edge transitive, 2 = arc transitive, 0 = neither - -c# connectivity (2 means 2 or more). - -kk# #-tree, otherwise 0. The complete graph K_n is tabulated as - an n-tree, but matches either n-1 or n, - -i# min common nbrs of adjacent vertices; -ii# maximum - -j# min common nbrs of non-adjacent vertices; -jj# maximum - -x# number of sources -xx# number of sinks - -WW# number of diamonds -HH# number of hexagons - -N# chromatic number (limited to WORDSIZE colours) - -NN# chromatic index (limited to max degree WORDSIZE-1) - -A# class (chromatic index - maximum degree + 1) - -G# connectivity -GG# edge connectivity - -Sort keys: - Counts are made for all graphs passing the constraints. Counts - are given separately for each combination of values occurring for - the properties listed as sort keys. A sort key is introduced by - ’--’ and uses one of the letters known as constraints. These can - be combined: --n --e --r is the same as --ne --r and --ner. - The order of sort keys is significant. - A comma can be used as a separator. -The sort key ’:’ has a special purpose: the values of sort keys - - - following ’:’ are given as ranges rather than creating a separate - line for each value. For example --e:zZ will give the ranges of - radius and diameter that occur for each number of edges. - The output format matches the input, except that sparse6 is used - to output an incremental graph whose predecessor is not output. - - Some sort keys have boolean variants with parameters: - --N# #-colourable (i.e. chromatic number <= #) - --NN# #-edge colourable - --G# #-connected (i.e. connectivity >= #) - --GG# #-edge connected - -===== countneg ====================================================== - -Usage: countneg [-ne] [infile] - - Count graphs by number of vertices and/or number of edges - - -n Count by vertices - -e Count by edges - Default and -ne are to count by both - -q Suppress auxiliary output. - Use countg instead if incremental inputs are present. - -===== cubhamg ====================================================== - -Usage: cubhamg [-#] [-v|-V] [-n#-#|-y#-#|-i|-I|-o|-O|-x|-e|-E] [-b|-t] [infile [outfile]] - -cubhamg : Find hamiltonian cycles in sub-cubic graphs - Graphs that are not hamiltonian, or not solved, are written out - infile is the name of the input file in graph6/sparse6 format - outfile is the name of the output file in the same format - - stdin and stdout are the defaults for infile and outfile - - The output file will have a header - if and only if the input file does. - - Optional switches: - - -# A parameter useful for tuning (default 100) - -v Report nonhamiltonian graphs and noncubic graphs - -V .. in addition give a cycle for the hamiltonian ones - (with -c, give count for each input) - -n#-# If the two numbers are v and i, then the i-th edge - out of vertex v is required to be not in the cycle. - It must be that i=1..3 and v=0..n-1. - -y#-# If the two numbers are v and i, then the i-th edge - - - out of vertex v is required to be in the cycle. - It must be that i=1..3 and v=0..n-1. - You can use any number of -n/-y switches to force edges. - Out of range first arguments are ignored. - If -y and -n specify the same edge, -y wins. - -i Test + property: for each edge e, there is a hamiltonian - cycle using e. - -I Test ++ property: for each pair of edges e,e’, there is - a hamiltonian cycle which uses both e and e’. - -o Test - property: for each edge e, there is a hamiltonian - cycle avoiding e - -O Test -- property: for each pair of nonadjacent edges e,e’s, - there is a hamiltonian cycle avoiding both. Note that - this is trivial unless the girth is at least 5. - -x Test +- property: for each pair of edges e,e’, there is - a hamiltonian cycle which uses e but avoids e’. - -e Test 3/4 property: for each edge e, at least 3 of the 4 - paths of length 3 passing through e lie on hamiltonian cycles. - -E Test 3/4+ property: for each edge e failing the 3/4 property, - all three ways of joining e to the rest of the graph are - hamiltonian avoiding e. - -T# Specify a timeout, being a limit on how many search tree - nodes are made. If the timeout occurs, the graph is - written to the output as if it is nonhamiltonian. - -R# Specify the number of repeat attempts for each stage. - -F Analyze covering paths from 2 or 4 vertices of degree 2. - - -b Require biconnectivity - -t Require triconnectivity (note: quadratic algorithm) - - -c Count hamiltonian cycles, output count for each graph. - -V, -n and -y can also be used. No graphs are output. - - -y, -n, -#, -R and -T are ignored for -i, -I, -x, -o, -e, -E, -F - -===== deledgeg ====================================================== - -Usage: deledgeg [-lq] [-v#] [-d#] [-z] [infile [outfile]] - -For each edge e, output G-e - - The output file has a header if and only if the input file does. - - -z Consider as digraph and delete directed edges - -l Canonically label outputs - -v# Only delete edges incident to this vertex (as head for digraph) - -d# Specify a lower bound on the minimum out-degree of the output - -q Suppress auxiliary information - - -===== delptg ====================================================== - -Usage: delptg [-lq] [-a|-b] [-d#|-d#:#] [-v#|-v#:#] [-A] [-r#] [-k#] [-n#] [-m#|-i] [infile - -Delete some vertices from a file of graphs. - - The output file has a header if and only if the input file does. - No isomorph reduction is done. - - -l Canonically label outputs - -d# -d#:# Only remove vertices with original degree in the given range - -k# Find the #-core (recursively remove vertices of degree less than k) - -n# The number of vertices to delete (default 1). - -A Delete all the vertices specified by -d and/or -v - -v# -v#:# Vertex number or numbers that it is allowed to delete - (the first vertex is number 0). - -m# Lower bound on minimum degree of output graphs. - -r# Choose # random sets of points (not necessarily different) - -S# Set random number seed (taken from clock otherwise). - -a The deleted points must be adjacent. - -b The deleted points must be non-adjacent. - -i Leave deleted vertices as isolates, not compatible with -m. - No empty graphs are output. No warning is issued if - -d, -v -n, -m together imply no graphs are output. - For digraphs, out-degree is used for -d and -m. - -q Suppress auxiliary information - -===== dimacs2g ====================================================== - -Usage: dimacs2g [-n#:#] [-a"string"] [-b"string"] [-d] -[c] [infile...] - -Read files of graphs in Dimacs format and write them to stdout. - - -d Use dreadnaut format (default is sparse6) - -n#:# Specify a range of n values for output - -a"string" A string to write before each graph. - -b"string" A string to write after each graph. - -a and -b only operate for dreadnaut output; - and should be given in separate arguments. - -c Don’t copy "c" comments from the input. - - Input files with name *.gz are ungzipped. - - - - -===== directg ====================================================== - -Usage: directg [-q] [-u|-T|-G] [-V] [-o|-a] [-f#] [-e#|-e#:#] [-s#/#] [infile [outfile]] - -Read undirected graphs and orient their edges in all possible ways. - Edges can be oriented in either or both directions (3 possibilities). - Isomorphic directed graphs derived from the same input are suppressed. - If the input graphs are non-isomorphic then the output graphs are also. - - -e# | -e#:# specify a value or range of the total number of arcs - -o orient each edge in only one direction, never both - -a only make acyclic orientations (implies -o) - -f# Use only the subgroup that fixes the first # vertices setwise - - -T use a simple text output format (nv ne edges) instead of digraph6 - -G like -T but includes group size as third item (if less than 10^10) - The group size does not include exchange of isolated vertices. - -V only output graphs with nontrivial groups (including exchange of - isolated vertices). The -f option is respected. - -u no output, just count them - -s#/# Make only a fraction of the orientations: The first integer is - the part number (first is 0) and the second is the number of - parts. Splitting is done per input graph independently. - -q suppress auxiliary information - -===== distgraphg ====================================================== - -Usage: distgraphg [-e|o|i] [-d#|-d#:#]... [-q] [infile [outfile]] - -Form graphs defined by distances in the input graphs. The -d,-e,-o-i - parameters define a set of distances. The output graph has an edge - if the distance in the input graph is in the set. - - -d# -d#:# Specify a range of allowed distances. - Can be repeated up to 100 times. - -i Include infinity (unreachable vertices) - -e, -o Only allow even or odd distances - - If none of -d,-e,-o,-i is present, the square of the graph is taken. - If -e or -o appear without -d, all even or all odd distances are allowed. - - The output file has a header if and only if the input file does. - - -q Suppress auxiliary information. - - - - -===== dretodot ====================================================== - -Usage: dretodot [-S#:#ixF#o#m#n#r#:#[r#]d#g] [infile.dre [outfile.dot [outfile.dre]]] - - Read graphs and initial coloring in dreadnaut format. -Write graphs in dot format to outfile.dot. -If outfile.dre is given, write the input graph and the partition, -as modified by the -F and -i options, to outfile.dre. outfile.dre -is allowed to be the same file as infile.dre. --V Set max number of vertices (default 1000). --E Set max number of edges (default 5000). --v Set verbose mode (default NO). --S#:# Set maximum width and height of the drawing, in inches -(default 10 x 6.18). --i Refine the partition before drawing (default NO). --x Draw the orbit partition, computed by Traces. (default NO). --F# Individualize vertex # (and refine the partition). --o# Label vertices starting at # (default 0). This can be -overridden in the input. --m# Set the drawing model (see http://www.graphviz.org): -0 (or any value different from 1,...,5)=dot (default 0), -1=neato, 2=fdp, 3=sfdp, 4=twopi, 5=circo. --n# Scale the size of vertices in the drawing (#=0,1,2; default 1). --r#:# (-r#) Set the vertices to be drawn at the topmost level -in a hierarchical (dot model) drawing (default none). -Any sequence of -r#:# (r#) options is allowed. --d# Draw the graph induced by vertices at topmost level -and by vertices at distance # from them; example: -./dretodot -n2 -r1 -r12:17 -d2 MyGraph.dre Outfile.dot. --g Highlight the induced subgraph into the whole graph. - -Only dreadnaut commands $,$$,g,n,f,",! are recognised; no digraphs. - -===== dretog ====================================================== - -Usage: dretog [-n#o#sghq] [infile [outfile]] - -Read graphs in dreadnaut format. - - -o# Label vertices starting at # (default 0). - This can be overridden in the input. - -n# Set the initial graph order to # (no default). - This can be overridden in the input. - -g Use graph6 format (default for undirected graphs). - -z Use digraph6 format (default for directed graphs). - -s Use sparse6 format. - -h Write a header (according to -g, -z or -s). - -q Suppress auxiliary output. - - - Input consists of a sequence of dreadnaut commands restricted to: - - n=# set number of vertices (no default) - The = is optional. - $=# set label of first vertex (default 0) - The = is optional. - d indicate graph will be directed - $$ return origin to initial value (see -o#) - ".." and !..\n comments to ignore - g specify graph to follow (as dreadnaut format) - Can be omitted if first character of graph is a digit or ’;’. - q exit (optional) - -===== edgetransg ====================================================== - -Usage: edgetransg [-t] [-q] [infile [outfile]] - -Select undirected graphs according to group action on vertices, edges and arcs. - Digraphs are not supported yet. - - The output file has a header if and only if the input file does. - - -v require vertex-transitive - -V require not vertex-transitive - -e require edge-transitive - -E require not edge-transitive - -a require arc-transitive - -A require not arc-transitive - -q Suppress auxiliary information. - -===== genbg ====================================================== - -Usage: genbg [-c -ugs -vq -lzF] [-Z#] [-D#] [-A] [-d#|-d#:#] [-D#|-D#:#] n1 n2 - [mine[:maxe]] [res/mod] [file] - -Find all bicoloured graphs of a specified class. - - n1 : the number of vertices in the first class - n2 : the number of vertices in the second class -mine:maxe : a range for the number of edges - #:0 means ’# or more’ except in the case 0:0 - res/mod : only generate subset res out of subsets 0..mod-1 - file : the name of the output file (default stdout) - -c : only write connected graphs - -z : all the vertices in the second class must have - different neighbourhoods - -F : the vertices in the second class must have at least two - - - neighbours of degree at least 2 - -L : there is no vertex in the first class whose removal leaves - the vertices in the second class unreachable from each other - -Y# : two vertices in the second class must have at least # common nbrs - -Z# : two vertices in the second class must have at most # common nbrs - -A : no vertex in the second class has a neighbourhood which is a - subset of another vertex’s neighbourhood in the second class - -D# : specify an upper bound for the maximum degree - Example: -D6. You can also give separate maxima for the - two parts, for example: -D5:6 - -d# : specify a lower bound for the minimum degree. - Again, you can specify it separately for the two parts: -d1:2 - -g : use graph6 format for output (default) - -s : use sparse6 format for output - -a : use Greechie diagram format for output - -u : do not output any graphs, just generate and count them - -v : display counts by number of edges to stderr - -l : canonically label output graphs (using the 2-part colouring) - - -q : suppress auxiliary output - - See program text for much more information. - -===== geng ====================================================== - -Usage: geng [-cCmtfkbd#D#] [-kTSPF] [-uygsnh] [-lvq] - [-x#X#] n [mine[:maxe]] [res/mod] [file] - -Generate all graphs of a specified class. - - n : the number of vertices -mine:maxe : a range for the number of edges - #:0 means ’# or more’ except in the case 0:0 - res/mod : only generate subset res out of subsets 0..mod-1 (see below) - - -c : only write connected graphs - -C : only write biconnected graphs - -t : only generate triangle-free graphs - -f : only generate 4-cycle-free graphs - -p : only generate 5-cycle-free graphs - -k : only generate K4-free graphs - -T : only generate chordal graphs - -S : only generate split graphs - -P : only generate perfect graphs - -F : only generate claw-free graphs - -b : only generate bipartite graphs - (-t, -f and -b can be used in any combination) -The combination -bT gives bipartite graphs with no - - - induced cycles longer than 4-cycles. - -m : save memory at the expense of time (only makes a - difference in the absence of -b, -t, -f and n <= 28). - -d# : a lower bound for the minimum degree - -D# : an upper bound for the maximum degree - -v : display counts by number of edges - -l : canonically label output graphs - - -u : do not output any graphs, just generate and count them - -g : use graph6 output (default) - -s : use sparse6 output - -h : for graph6 or sparse6 format, write a header too - - -q : suppress auxiliary output (except from -v) - -res/mod splitting is controlled by two parameters -X# and -x# whose default -values are displayed when splitting is used. Increasing them will make the -division into parts more even at the expense of more overhead, but you must -use the same values for all parts. Splitting obeys the laws of modular -arithmetic, for example 3/7 is the union of 3/14 and 10/14, but when -subdividing like this you must manually provide the same -X and -x values -to the smaller parts. - -===== genktreeg ====================================================== - -Usage: genktreeg [-k#] [-lq] n [res/mod] [file] - -Generate all k-trees on n vertices. - - n : the number of vertices - -k# : the value of k (default 2) - res/mod : only generate subset res out of subsets 0..mod-1 - - -l : canonically label output graphs - - -u : do not output any graphs, just generate and count them - -g : use graph6 output (default) - -s : use sparse6 output - -h : write a header (only with -g or -s) - - -q : suppress auxiliary output - - - - -===== genposetg ====================================================== - -Usage: genposetg n [o|t] [q] [m x y] where n <= 16 is the number of points - Generate the Hasse diagrams of the posets with n points - o causes digraph6 output in arbitrary order to be written to stdout - t causes digraph6 output in topological order to be written to stdout - c restricts the program to connected posets - q supresses statistics except for the final count - m x y with 0 <= x < y divides the generation - into y parts and writes only part x. - -===== genquarticg ====================================================== - -Usage: genquarticg [-ugs -h -c -l] n [res/mod] [file] - - generate all non-isomorphic quartic graphs of a given order - - n : the number of the vertices - file : the name of the output file (default stdout) - -u : do not output any graphs, just generate and count them - -g : use graph6 format for output (default) - -s : use sparse6 format for output - -h write a header (only with -g or -s). - -c : only write connected graphs - -C : only write biconnected graphs - res/mod : only generate subset res out of subsets 0..mod-1 - -l : canonically label output graphs. - -===== genrang ====================================================== - -Usage: genrang [-P#|-P#/#|-e#|-r#|-R#|-d#] [-M#] [-l#] [-m#] [-t] [-T] [-a] - [-s|-g|-z] [-S#] [-q] n|n1,n2 num [outfile] - -Generate random graphs. - n : number of vertices - n1,n2 : number of vertices (bipartite graph) - num : number of graphs - - A bipartite variant is only available if specified below. - - -s : Write in sparse6 format (default) - -g : Write in graph6 format - -z : Make random digraphs and write in digraph6 format - -P#/# : Give edge probability; -P# means -P1/#. - Bipartite version available. - -e# : Give the number of edges - Bipartite version available. - -r# : Make regular of specified degree - - - -d# : Make regular of specified degree (pseudorandom) - With -z, #-in #-out digraph without loops - Bipartite version: this is the degree on the first side. - -M# : In conjunction with -d, make the distribution more uniform - by running a Markov chain for #*n steps starting at the - pseudorandom graph. - -R# : Make regular of specified degree but output - as vertex count, edge count, then list of edges - -l# : Maximum loop multiplicity (default 0) - -m# : Maximum multiplicity of non-loop edge (default and minimum 1) - -t : Make a random spanning tree of a complete graph - or complete bipartite graph - -T : Make a random tournament (implies -z) - -a : Make invariant under a random permutation - -S# : Specify random generator seed (default nondeterministic) - -q : suppress auxiliary output - -===== genspecialg ====================================================== - -Usage: genspecialg [-s|-g|-z|-d|-v] [-q] [graph options]... [outfile] - -Generate special graphs. - # : size parameter called n in the descriptions - - -s : Write in sparse6 format (default) - -g : Write in graph6 format - -z : Make digraph versions and write in digraph6 format - -d : Write in dreadnaut format (can be used with -z) - -v : For each graph, report the size to stderr - -q : Suppress summary - - If defined, the digraph version is shown in : - -p# : path on n vertices - -c# : cycle on n vertices - -e# : empty graph on n vertices - -k# : complete graph on n vertices - -b#,#[,#] : complete bipartite graph r> on n vertices - minus a matching of given size if present - -m#,#... : multipartite graph - -a# : antiprism on 2n - -l# : moebius ladder with # vertices - -D#,# : de Bruijn graph . D(m,t) has order m^t - -w# : wheel with # spokes - -f# : flower snark on 4n vertices - -L# : triangular graph, the linegraph of K_n - -P#,# : generalized Petersen graph; usual one is -P5,2 - -Q# -Q#,# : hypercube on 2^n vertices. Q(n,t) has vertices {0,1}^n - and edges for hamming distance t. t=1 is default. - - - -A# : connected antiregular graph on n vertices - -J#,# : Johnson graph J(n,k), args are n and k - -K#,# -K#,#,# : Generalized Kneser graph. K(n,k,t) is graph of k-subsets - of an n-set whose intersection is t. Default for t is 0. - -C#,#... : circulant graph; first arg is the number of vertices - -T#,#... : theta graph Theta(#,#,...), give path lengths - -G#,#... : grid, use negative values for open directions - -Y# : Paley graph or digraph, depending on size. Nondeterministic. - -X# : produce a named graph, # can be an index or a partial name. - Use genspecialg --Xhelp for a list. - - Any number of graphs can be generated at once. - -Arguments for genspecialg -X. Either the index or an unambigous prefix of - the case-insensitive name can be used. The -g switch is ignored. -index graph name vertices degree edges girth -150 ArmaniosWellsGraph 32 5 80 5 - 1 Balaban10CageGraph 70 3 105 10 - 2 Balaban11CageGraph 112 3 168 11 - 3 BarnetteBosakLederbergGraph 38 3 57 4 - 4 BerlekampVanLintSeidelGraph 243 22 2673 3 - 5 BidiakisCube 12 3 18 4 - 6 BiggsSmithGraph 102 3 153 9 - 7 BlanusaSnark1 18 3 27 5 - 8 BlanusaSnark2 18 3 27 5 - 9 BrinkmannGraph 21 4 42 5 - 10 BrouwerHaemersGraph 81 20 810 3 - 11 Cage39Graph1 58 3 87 9 - 12 Cage39Graph10 58 3 87 9 - 13 Cage39Graph11 58 3 87 9 - 14 Cage39Graph12 58 3 87 9 - 15 Cage39Graph13 58 3 87 9 - 16 Cage39Graph14 58 3 87 9 - 17 Cage39Graph15 58 3 87 9 - 18 Cage39Graph16 58 3 87 9 - 19 Cage39Graph17 58 3 87 9 - 20 Cage39Graph18 58 3 87 9 - 21 Cage39Graph2 58 3 87 9 - 22 Cage39Graph3 58 3 87 9 - 23 Cage39Graph4 58 3 87 9 - 24 Cage39Graph5 58 3 87 9 - 25 Cage39Graph6 58 3 87 9 - 26 Cage39Graph7 58 3 87 9 - 27 Cage39Graph8 58 3 87 9 - 28 Cage39Graph9 58 3 87 9 - 29 Cage46Graph 30 4 60 6 - 30 Cage47Graph 67 4 134 7 - 31 Cage48Graph 80 4 160 8 - - - 32 Cage58Graph 170 5 425 8 -127 Cage66Graph 62 6 186 6 - 33 Cage68Graph 312 6 936 8 - 34 Cage76Graph 90 7 315 6 - 35 CameronGraph 231 30 3465 3 -128 ChangGraph1 28 12 168 3 -129 ChangGraph2 28 12 168 3 - 36 ChangGraph3 28 12 168 3 - 37 ChvatalGraph 12 4 24 4 - 38 ClebschGraph 16 5 40 4 -151 ConwaySmithGraph 63 10 315 3 -154 CoolsaetDegraerGraph 42 13 273 3 - 39 CoxeterGraph 28 3 42 7 - 40 DejterGraph 112 6 336 4 -153 DelsarteGraph 243 110 13365 3 - 41 DesarguesGraph 20 3 30 6 - 42 DodecahedronGraph 20 3 30 5 -130 DoobGraph1 64 9 288 3 -131 DoobGraph2 256 12 1536 3 -152 DoroGraph 68 12 408 3 - 43 DoubleStarSnark 30 3 45 6 - 44 DoyleGraph 27 4 54 5 - 45 DuererGraph 12 3 18 4 - 46 DyckGraph 32 3 48 6 - 47 EllinghamHorton54 54 3 81 6 - 48 EllinghamHorton78 78 3 117 6 - 49 ErreraGraph 17 5-6 45 3 - 50 FolkmanGraph 20 4 40 4 - 51 FosterCageGraph 30 5 75 5 - 52 FosterGraph 90 3 135 10 - 53 FranklinGraph 12 3 18 4 - 54 FruchtGraph 12 3 18 3 - 55 GeneralizedHexagonGraph 126 3 189 12 -134 GeneralizedOctagon45 45 4 90 3 -132 GeneralizedOctagon160 160 6 480 3 -133 GeneralizedOctagon425 425 8 1700 3 - 56 GeorgesGraph 50 3 75 6 - 57 GewirtzGraph 56 10 280 4 -156 GoethalsSeidelGraph 105 32 1680 3 - 58 GoldnerHararyGraph 11 3-8 27 3 - 59 GolombGraph 10 3-6 18 3 - 60 GossetGraph 56 27 756 3 -135 GrassmannGraph1 35 18 315 3 -136 GrassmannGraph2 155 42 3255 3 -137 GrassmannGraph3 651 90 29295 3 - 61 GrayGraph 54 3 81 8 - 62 GreatRhombicosidodecahedralGraph 120 3 180 4 - 63 GreatRhombicuboctahedralGraph 48 3 72 4 - - - 64 GrinbergGraph 46 3 69 5 -155 GritsenkoGraph 65 32 1040 3 - 65 GroetzschGraph 11 3-5 20 4 -138 HallGraph 65 10 325 3 - 66 HallJankoGraph 100 36 1800 3 -139 HallJankoNearOctagon 315 10 1575 3 - 67 HarborthGraph 52 4 104 3 - 68 HarriesGraph 70 3 105 10 - 69 HarriesWongGraph 70 3 105 10 - 70 HatzelGraph 57 3-4 88 4 - 71 HeawoodGraph 14 3 21 6 - 72 HerschelGraph 11 3-4 18 4 - 73 HigmanSimsGraph 100 22 1100 4 - 74 HoffmanGraph 16 4 32 4 - 75 HoffmanSingletonGraph 50 7 175 5 - 76 HortonGraph92 92 3 138 6 - 77 HortonGraph96 96 3 144 6 - 78 IcosahedronGraph 12 5 30 3 - 79 IcosidodecahedralGraph 30 4 60 3 - 80 KittellGraph 23 5-7 63 3 - 81 KleinGraph 24 7 84 3 -149 KoolenRiebeekGraph.s6 486 45 10935 4 - 82 KrackhardtKiteGraph 10 1-6 18 3 -140 KummerGraph1 32 6 96 4 -141 KummerGraph2 36 6 108 4 -142 LeonardGraph 288 12 1728 4 - 83 LivingstoneGraph 266 11 1463 5 - 84 LjubljanaGraph 112 3 168 10 - 85 LoupekineSnark1 22 3 33 5 - 86 LoupekineSnark2 22 3 33 5 - 87 M22Graph 77 16 616 4 - 88 MarkstroemGraph 24 3 36 3 - 89 McGeeGraph 24 3 36 7 - 90 McLaughlinGraph 275 112 15400 3 - 91 MeredithGraph 70 4 140 4 - 92 MeringerGraph 30 5 75 5 -143 Mesner-WittGraph 77 16 616 4 - 93 MirzakhaniGraph 63 4-42 183 3 - 94 MoebiusKantorGraph 16 3 24 6 - 95 NauruGraph 24 3 36 6 - 96 OctahedronGraph 6 4 12 3 - 97 PappusGraph 18 3 27 6 - 98 PerkelGraph 57 6 171 5 - 99 PetersenGraph 10 3 15 5 -100 PoussinGraph 15 4-6 39 3 -101 RobertsonGraph 19 4 38 5 -102 RobertsonWegnerGraph 30 5 75 5 -103 SchlaefliGraph 27 16 216 3 - - -104 ShrikhandeGraph 16 6 48 3 -125 Skeleton120cell 600 4 1200 5 -126 Skeleton600cell 120 12 720 3 -105 SmallRhombicosidodecahedralGraph 60 4 120 3 -106 SnubCubicalGraph 24 5 60 3 -107 SnubDodecahedralGraph 60 5 150 3 -108 SoccerBallGraph 60 3 90 5 -109 SousselierGraph 16 3-5 27 5 -110 SuzukiGraph 1782 416 370656 3 -111 SylvesterGraph 36 5 90 5 -144 SuetakeGraph 72 12 432 4 -112 SzekeresSnark 50 3 75 5 -145 TesseractGraph 16 4 32 4 -113 TietzeGraph 12 3 18 3 -114 TriangleReplacedCoxeterGraph 84 3 126 3 -115 TriangleReplacedPetersenGraph 30 3 45 3 -116 TruncatedDodecahedralGraph 60 3 90 3 -117 TruncatedIcosahedralGraph 60 3 90 5 -118 TruncatedOctahedralGraph 24 3 36 4 -119 TruncatedTetrahedralGraph 12 3 18 3 -120 Tutte8CageGraph 30 3 45 8 -146 Tutte12Cage 126 3 189 12 -147 VanLintSchrijverGraph 162 6 486 6 -121 WaltherGraph 25 1-3 31 4 -122 WellsGraph 32 5 80 5 -123 WienerArayaGraph 42 3-4 67 4 -124 WongGraph 30 5 75 5 -148 ZaraGraph 126 45 2835 3 - -===== gentourng ====================================================== - -Usage: gentourng [-cd#D#] [-ugsz] [-lq] n [res/mod] [file] - -Generate all tournaments of a specified class. - - n : the number of vertices - res/mod : only generate subset res out of subsets 0..mod-1 - - -c : only write strongly-connected tournaments - -d# : a lower bound for the minimum out-degree - -D# : a upper bound for the maximum out-degree - -l : canonically label output graphs - - -u : do not output any graphs, just generate and count them - -g : use graph6 output (lower triangle) - -s : use sparse6 output (lower triangle) - -z : use digraph6 output - -h : write a header (only with -g or -s) - - - Default output is upper triangle row-by-row in ascii - - -q : suppress auxiliary output - - See program text for much more information. - -===== gentreeg ====================================================== - -Usage: gentreeg [-D#] [-Z#:#] [-ulps] [-q] n|n1:n2 [res/mod] [file] - -Generate (unrooted) trees. - - n, n1:n2 : the number of vertices or a range - Outputs are in order of the number of vertices. - res/mod : only generate subset res out of subsets 0..mod-1 - - -D# : an upper bound for the maximum degree - -Z#:# : bounds for the diameter - - -s : use sparse6 output (default) - -p : write a parent array - -l : write a level array - -u : do not output any graphs, just generate and count them - - -q : suppress auxiliary output - - See program text for much more information. - -===== hamheuristic ====================================================== - -Usage: hamheuristic [-sgu] [-vq] [-V] [-L#] [-t#] [infile [outfile]] - -Apply a heuristic for finding hamiltonian cycles. - Output those which are unsuccessful. - - -s force output to sparse6 format - -g force output to graph6 format - If neither -s or -g are given, the output format is - determined by the header or, if there is none, by the - format of the first input graph. - -V Write those for which a cycle (path with -p) is found instead - -u Suppress output to outfile, give statistics instead. - - The output file will have a header if and only if the input file does. - - -p Be content with a hamiltonian path - -v Give a cycle or path if one is found. - -c If a cycle or path is found, perform an independent check of it. - - - -L# Limit number of sideways steps (default 1000+40*n) - -t# Try # times (default 1) - - -q suppress auxiliary information - -===== labelg ====================================================== - -Usage: labelg [-q] [-sgz | -C#W#] [-fxxx] [-S|-t] - [-i# -I#:# -K#] [infile [outfile]] - -Canonically label a file of graphs or digraphs. - - -s force output to sparse6 format - -g force output to graph6 format - -z force output to digraph6 format - If neither -s, -g or -z are given, the output format is - determined by the header or, if there is none, by the - format of the first input graph. As an exception, digraphs - are always written in digraph6 format. - -S Use sparse representation internally. - Note that this changes the canonical labelling. - Multiple edges are not supported. One loop per vertex is ok. - -t Use Traces. - Note that this changes the canonical labelling. - Multiple edges and loops are not supported, nor invariants. - - -C# Make an invariant in 0..#-1 and output the number of graphs - with each value of the invariant. Don’t write graphs unless - -W too. - -W# (requires -C) Output the graphs with this invariant value, - in their original labelling. Don’t write the table. - - The output file will have a header if and only if the input file does. - - -fxxx Specify a partition of the vertex set. xxx is any - string of ASCII characters except nul. This string is - considered extended to infinity on the right with the - character ’z’. The sequence ’x^N’, where x is a character and N is - a number, is equivalent to writing ’x’ N times. One character is - associated with each vertex, in the order given. The labelling - used obeys these rules: - (1) the new order of the vertices is such that the associated - characters are in ASCII ascending order - (2) if two graphs are labelled using the same string xxx, - the output graphs are identical iff there is an - associated-character-preserving isomorphism between them. - If a leading ’-’ is used, as in -f-xxx, the characters are - assigned to the vertices starting at the last vertex, and - - - the new order of the vertices respects decreasing ASCII order. - - -i# select an invariant (1 = twopaths, 2 = adjtriang(K), 3 = triples, - 4 = quadruples, 5 = celltrips, 6 = cellquads, 7 = cellquins, - 8 = distances(K), 9 = indsets(K), 10 = cliques(K), 11 = cellcliq(K), - 12 = cellind(K), 13 = adjacencies, 14 = cellfano, 15 = cellfano2, - 16 = refinvar(K)) - -I#:# select mininvarlevel and maxinvarlevel (default 1:1) - -K# select invararg (default 3) - - -q suppress auxiliary information - -===== linegraphg ====================================================== - -Usage: linegraphg [-t] [-q] [infile [outfile]] - -Take the linegraphs of a file of graphs. - Input graphs with no edges produce only a warning message. - - The output file has a header if and only if the input file does. - - -t make the total graph - -q Suppress auxiliary information. - -===== listg ====================================================== - -Usage: listg [-fp#:#l#o#Ftq] [-a|-A|-c|-d|-e|-H|-M|-W|-L|S|-s|-b|-G|-y|-Yxxx] - [infile [outfile]] - -Write graphs in human-readable format. - - -f : assume inputs have same size (only used from a file - and only if -p is given) - -p#, -p#:#, -p#-# : only display one graph or a sequence of - graphs. The first graph is number 1. A second number - which is empty or zero means infinity. - This option won’t work for incremental input. - -a : write as adjacency matrix, not as list of adjacencies - -A : same as -a with a space between entries - -l# : specify screen width limit (default 78, 0 means no limit) - This is not currently implemented with -a or -A. - -o# : specify number of first vertex (default is 0). - -d : write output to satisfy dreadnaut - -c : write ascii form with minimal line-breaks - -e : write a list of edges, preceded by the order and the - number of edges - -M : write in Magma format - -m : write in Mathematica format - - - -W : write matrix in Maple format - -H : write in HCP operations research format - -T : write in the edge-list format needed by the program tutte - -L : (only with -M or -W) write Laplacian rather than adjacency matrix - -S : (only with -M or -W) write signless Laplacian not adjacency matrix - -b : write in DIMACS format - -G : write in GRAPE format - -y : write in dot file format - -Yxxx : extra dotty commands for dot files (arg continues to end of param) - -t : write upper triangle only (affects -a, -A, -d and default) - -s : write only the numbers of vertices and edges - -F : write a form-feed after each graph except the last - -q : suppress auxiliary output - - -a, -A, -c, -d, -M, -W, -H and -e are incompatible. - -===== multig ====================================================== - -Usage: multig [-q] [-V] [-u|-T|-G|-A|-B] [-e#|-e#:#] - [-m#] [-f#] [-D#|-r#|-l#] [infile [outfile]] - -Read undirected loop-free graphs and replace their edges with multiple - edges in all possible ways (multiplicity at least 1). - Isomorphic multigraphs derived from the same input are suppressed. - If the input graphs are non-isomorphic then the output graphs are also. - - -e# | -e#:# specify a value or range of the total number of edges - counting multiplicities - -m# maximum edge multiplicity (minimum is 1) - -D# upper bound on maximum degree - -r# make regular of specified degree (incompatible with -l, -D, -e) - -l# make regular multigraphs with multiloops, degree # - (incompatible with -r, -D, -e) - -f# Use the group that fixes the first # vertices setwise - -V read the T format as produced by vcolg and obey the vertex colours - in computing the automorphism group. If -T or -G is used as the - output format, a list of the input colours is included. - Either -l, -r, -D, -e or -m with a finite maximum must be given - -T use a simple text output format (nv ne {v1 v2 mult}) - -G like -T but includes group size as third item (if less than 10^10) - The group size does not include exchange of isolated vertices. - -A write as the upper triangle of an adjacency matrix, row by row, - including the diagonal, and preceded by the number of vertices - -B write as an integer matrix preceded by the number of rows and - number of columns, where -f determines the number of rows - -u no output, just count them - -q suppress auxiliary information - - - -===== nbrhoodg ====================================================== - -Usage: nbrhoodg [-lq] [-c|-C] [-d#|d#:#] [-v#|-v#:#] [infile [outfile]] - -Extract neighbourhoods of vertices of a graph. - - The output file has a header if and only if the input file does. - No isomorph reduction is done. No null graphs are written. - - -l Canonically label outputs (default is same labelling as input) - -C Extract closed neighbourhoods instead. - -c Extract non-neighbourhoods instead. - -D# Extract neighbourhoods out to distance # (implies -C) - -d# -d#:# Only include vertices with original degree in the given range - -v# -v#:# Only include vertices with these vertex numbers (first is 0). - No empty graphs are output. - For digraphs, out-degree and out-neighbourhoods are used. - -q Suppress auxiliary information - -===== newedgeg ====================================================== - -Usage: newedgeg [-lq] [infile [outfile]] - -For each pair of non-adjacent edges, output the graph obtained - by subdividing the edges and joining the new vertices. - - The output file has a header if and only if the input file does. - - -l Canonically label outputs - -q Suppress auxiliary information - -===== NRswitchg ====================================================== - -Usage: NRswitchg [-lq] [infile [outfile]] - -For each v, complement the edges from N(v) to V(G)-N(v)-v. - - The output file has a header if and only if the input file does. - - -l Canonically label outputs. - -q Suppress auxiliary information. - - - - -===== pickg ====================================================== - -Usage: [pickg|countg] [-fp#:#q -V -X] [--keys] [-constraints -v] [ifile [ofile]] - -countg : Count graphs according to their properties. - pickg : Select graphs according to their properties. - - ifile, ofile : Input and output files. - ’-’ and missing names imply stdin and stdout. - - Miscellaneous switches: - -p# -p#:# Specify range of input lines (first is 1) - May fail if input is incremental. - -f With -p, assume input lines of fixed length - (only used with a file in graph6/digraph6 format) - -v Negate all constraints (but not -p) - -X Reverse selection (but -p still observed) - -V List properties of every input matching constraints. - -l Put a blank line whenever the first parameter changes, - if there are at least two parameters. - -1 Write output as lines of numbers separated by spaces, - with 0/1 for boolean and both endpoints of ranges given - separately even if they are the same, and the count at - the end of the line. Also, no total is written. - -2 The same as -1 but counts are not written. - -9 Flush the output after each graph (expensive if many graphs) - -q Suppress informative output. - - Constraints: - Numerical constraints (shown here with following #) can take - a single integer value, or a range like #:#, #:, or :#. Each - can also be preceded by ’~’, which negates it. (For example, - -~D2:4 will match any maximum degree which is _not_ 2, 3, or 4.) - Constraints are applied to all input graphs, and only those - which match all constraints are counted or selected. - - -n# number of vertices -e# number of edges - -ee# number of non-edges (including loops for digraphs) - -L# number of loops -C strongly connected - -LL# number of 2-cycles -cc# number of components - -d# minimum (out-)degree -D# maximum (out-)degree - -m# vertices of min (out-)degree -M# vertices of max (out-)degree - -u# minimum (in-)degree -U# maximum (in-)degree - -s# vertices of min (in-)degree -S# vertices of max (in-)degree - -r regular -b bipartite - -z# radius -Z# diameter - -g# girth (0=acyclic) -Y# total number of cycles - -h# maximum independent set -k# maximum clique - - - -T# number of triangles -K# number of maximal cliques - -TT# number independent 3-sets -P# number of 5-cycles - -B# smallest possible first side of a bipartition (0 if nonbipartite) - -H# number of induced cycles -W# number of 4-cycles - -E Eulerian (all degrees are even, connectivity not required) - -a# group size -o# orbits -F# fixed points -t vertex-transitive - -O# number of orbits of edges -OO# number of orbits of arcs - -tt# 1 = edge transitive, 2 = arc transitive, 0 = neither - -c# connectivity (2 means 2 or more). - -kk# #-tree, otherwise 0. The complete graph K_n is tabulated as - an n-tree, but matches either n-1 or n, - -i# min common nbrs of adjacent vertices; -ii# maximum - -j# min common nbrs of non-adjacent vertices; -jj# maximum - -x# number of sources -xx# number of sinks - -WW# number of diamonds -HH# number of hexagons - -N# chromatic number (limited to WORDSIZE colours) - -NN# chromatic index (limited to max degree WORDSIZE-1) - -A# class (chromatic index - maximum degree + 1) - -G# connectivity -GG# edge connectivity - - Sort keys: - Counts are made for all graphs passing the constraints. Counts - are given separately for each combination of values occurring for - the properties listed as sort keys. A sort key is introduced by - ’--’ and uses one of the letters known as constraints. These can - be combined: --n --e --r is the same as --ne --r and --ner. - The order of sort keys is significant. - A comma can be used as a separator. - The sort key ’:’ has a special purpose: the values of sort keys - following ’:’ are given as ranges rather than creating a separate - line for each value. For example --e:zZ will give the ranges of - radius and diameter that occur for each number of edges. - The output format matches the input, except that sparse6 is used - to output an incremental graph whose predecessor is not output. - - Some sort keys have boolean variants with parameters: - --N# #-colourable (i.e. chromatic number <= #) - --NN# #-edge colourable - --G# #-connected (i.e. connectivity >= #) - --GG# #-edge connected - -===== planarg ====================================================== - -Usage: planarg [-v] [-nVq] [-p|-u] [infile [outfile]] - -For each input, write to output if planar. - - The output file has a header if and only if the input file does. - - - -v Write non-planar graphs instead of planar graphs - -V Write report on every input - -u Don’t write anything, just count - -p Write in planar_code if planar (without -p, same format as input) - -P Like -p but big-endian (same for <= 255 vertices) - -k Follow each non-planar output with an obstruction in sparse6 - format (implies -v, incompatible with -p) - -n Suppress checking of the result - -q Suppress auxiliary information - - This program permits multiple edges and loops - -===== productg ====================================================== - -Usage: productg [-u|-c|-l|-L|-k|-t|-a#] [infile [outfile]] - -Read two graphs in graph6/sparse6 format and write their product - in sparse6 or dreadnaut format. - -d : Dreadnaut format (default is sparse6) - - -c : Cartesian product - -l : Lexicographic product (G1[G2]) - -L : Lexicographic product (G2[G1]) - -t : Tensor (Kronecker, categorical, direct) product - -k : Complete (strong, normal) product - -a# : general case (argument is a 3-digit octal number) - Add these values giving the condition for an edge: - Code: 400 200 100 040 020 010 004 002 001 - Graph1: same same same adj adj adj nonadj nonadj nonadj - Graph2: same adj nonadj same adj nonadj same adj nonadj - - -u : Disjoint union - - -q : Suppress informative output - -===== ranlabg ====================================================== - -Usage: ranlabg [-q] [-f#] [-m#] [-S#] [infile [outfile]] - -Randomly relabel graphs. - - The output file has a header if and only if the input file does. - Each graph is written in the same format as it is read. - - -f# Don’t relabel the first # vertices. - -m# Output # randomly labelled copies of each input (default 1). - -S# Set random number seed (taken from clock otherwise). - - - -q Suppress auxiliary information. - -===== ransubg ====================================================== - -Usage: ransubg [-lq] [-P#|-P#/#] [-z] [-o] [-m#] [-S#] [infile [outfile]] - -Extract random graph/digraphs of a file of graphs. - - The output file has a header if and only if the input file does. - The output format is defined by the header or first graph, - but is always digraph6 if -z is used. - - -z Treat the input as a directed graph - -o Treat the input as a directed graph and output an oriented graph - -P# or -P#/# Specify a probability p. -P# is the same as -P1/# - -m# Make this many outputs for each input (default 1) - -l Canonically label outputs. - -S# Set seed for random numbers (default nondeterministic) - - Usually each edge is kept with probability p. - In the case of -o, each edge in one direction only is kept - with probability p. For edges in both directions, with probability p - keep one direction randomly chosen and with probability 1-p delete - both directions. Thus -oP1 will make a random orientation of an - undirected graph. - -q Suppress auxiliary information. - -===== shortg ====================================================== - -Usage: shortg [-qvkdu] [-i# -I#:# -K#] [-fxxx] [-S|-t] [-Tdir] [-Z#] [infile [outfile]] - - Remove isomorphs from a file of graphs. - - If outfile is omitted, it is taken to be the same as infile - If both infile and outfile are omitted, input will be taken - from stdin and written to stdout - - The output file has a header if and only if the input file does. - - -s force output to sparse6 format - -g force output to graph6 format - -z force output to digraph6 format - If none of -s, -z, -g are given, the output format is determined - by the header or, if there is none, by the format of the first - input graph. The output format determines the sorting order too. - As an exception, digraphs are always written in digraph6 format. - -S Use sparse representation internally. Note that this changes the - - - canonical labelling. - Multiple edges are not supported. One loop per vertex is ok. --t Use Traces. - Note that this changes the canonical labelling. - Multiple edges,loops, directed edges are not supported, - nor invariants. - --k output graphs have the same labelling and format as the inputs. - Without -k, output graphs have canonical labelling. - -s, -g, -z are ineffective if -k is given. - --v write to stderr a list of which input graphs correspond to which - output graphs. The input and output graphs are both numbered - beginning at 1. A line like - 23 : 30 154 78 - means that inputs 30, 154 and 78 were isomorphic, and produced - output 23. - --d include in the output only those inputs which are isomorphic - to another input. If -k is specified, all such inputs are - included in their original labelling. Without -k, only one - member of each nontrivial isomorphism class is written, - with canonical labelling. - --fxxx Specify a partition of the vertex set. xxx is any - string of ASCII characters except nul. This string is - considered extended to infinity on the right with the - character ’z’. The sequence ’x^N’, where x is a character and N is - a number, is equivalent to writing ’x’ N times. One character is - associated with each vertex, in the order given. The labelling - used obeys these rules: - (1) the new order of the vertices is such that the associated - characters are in ASCII ascending order - (2) if two graphs are labelled using the same string xxx, - the output graphs are identical iff there is an - associated-character-preserving isomorphism between them. - If a leading ’-’ is used, as in -f-xxx, the characters are - assigned to the vertices starting at the last vertex, and - the new order of the vertices respects decreasing ASCII order. - --i# select an invariant (1 = twopaths, 2 = adjtriang(K), 3 = triples, - 4 = quadruples, 5 = celltrips, 6 = cellquads, 7 = cellquins, - 8 = distances(K), 9 = indsets(K), 10 = cliques(K), 11 = cellcliq(K), - 12 = cellind(K), 13 = adjacencies, 14 = cellfano, 15 = cellfano2, - 16 = refinvar(K)) --I#:# select mininvarlevel and maxinvarlevel (default 1:1) --K# select invararg (default 3) - - - - -u Write no output, just report how many graphs it would have output. - In this case, outfile is not permitted. - -Tdir Specify that directory "dir" will be used for temporary disk - space by the sort subprocess. The default is usually /tmp. - -Z# Specify memory for sorting (number followed by %,K,M, or G) - -q Suppress auxiliary output - -===== showg ====================================================== - -Usage: showg [-p#:#l#o#Ftq] [-a|-A|-c|-d|-e] [infile [outfile]] - -Write graphs in human-readable format. - - infile is the input file in graph6, sparse6 or digraph6 format - This program does not support incremental sparse6 files; use listg. - outfile is the output file - Defaults are standard input and standard output. - - -p#, -p#:#, -p#-# : only display one graph or a sequence of - graphs. The first graph is number 1. A second number - which is empty or zero means infinity. - - -a : write the adjacency matrix - -A : same as -a with a space between entries - -d : write output to satisfy dreadnaut - -c : write compact dreadnaut form with minimal line-breaks - -e : write a list of edges, preceded by the order and the - number of edges - - -o# : specify number of first vertex (default is 0) - -t : write upper triangle only (affects -a, -A, -d and default) - -F : write a form-feed after each graph except the last - -l# : specify screen width limit (default 78, 0 means no limit) - This is not currently implemented with -a or -A. - -q : suppress auxiliary output - - -a, -A, -c, -d and -e are incompatible. - -===== subdivideg ====================================================== - -Usage: subdivideg [-k#] [-i] [-q] [infile [outfile]] - -Make the subdivision graphs of a file of graphs, or the inverse operation. - -k# Subdivide each edge by # new vertices (default 1) - -i Perform homeomorphic series reduction - For undirected graphs, repeatedly replace x--y--z by x--z if - x,y are not adjacent and y has no other neighbours. - For digraphs, repeatedly replace x->y->z by x->z if x,z are - - - distinct, x->z is not present, and y has no other neighbours. - - The output file has a header if and only if the input file does. - - -q Suppress auxiliary information. - -===== twohamg ====================================================== - -Usage: twohamg [-sgvq] [-L#] [infile [outfile]] - -Partition quartic graphs into two hamiltonian cycles. - Output those which cannot be partitioned. - - -s force output to sparse6 format - -g force output to graph6 format - If neither -s or -g are given, the output format is - determined by the header or, if there is none, by the - format of the first input graph. Also see -S. - - The output file will have a header if and only if the input file does. - - -p Read a cubic graph and use its prism. Vertex i of the input becomes - vertices 2*i,2*i+1 in the prism. - -x Test for decompositions using each 2-path - -X As -x but only output if two 2-paths are missed at some vertex - -y Test for decompositions using each non-triangular 3-path - -t# With -x and -X, consider only paths with center # - With -y, consider only paths starting at # - -Y With -p, only consider paths whose central edge is vertical - -v Give a partition for those graphs who have one and a message - for those which don’t. With -x, list exceptional 2-paths. - -L# Limit to 1000*# iterations; write with message if timeout. - Graphs that time out are written to the output. - - -q suppress auxiliary information - -===== underlyingg ====================================================== - -Usage: underlyingg [-q] [infile [outfile]] - -Take the underlying undirected graphs of a file of graphs. - - The output file has no header. - Undirected graphs are passed through without change, while - Underlying graphs of digraphs are written in sparse6 format. - - -q Suppress auxiliary information. - - - -===== uniqg ====================================================== - -Usage: uniqg [-q] [-xFILE] [-Xfile] [-hFILE] [-fxxx] [-u|-S|-t] - [-c] [-k] [-i# -I#:# -K#] [infile [outfile]] - -Remove duplicates from a file of graphs or digraphs. - The SHA256 cryptographic hash function is used for comparisons - - -S Use sparse representation internally. - Note that this changes the canonical labelling. - Multiple edges are not supported. One loop per vertex is ok. - -t Use Traces. - - -u No output, just count - -H Write hash codes, not graphs (note: binary output) - -k Write the input graph exactly, not a canonical graph - -c Assume graphs from infile are canonically labelled already - - -xFILE Read a file of graphs and exclude them from the output - -XFILE Like -xFILE but assume they are already canonically labelled - -hFILE Read a file of hash codes and exclude them from the output - -F Flush output for each new graph (expensive if there are many) - - -fxxx Specify a partition of the vertex set. xxx is any - string of ASCII characters except nul. This string is - considered extended to infinity on the right with the - character ’z’. The sequence ’x^N’, where x is a character and N is - a number, is equivalent to writing ’x’ N times. One character is - associated with each vertex, in the order given. The labelling - used obeys these rules: - (1) the new order of the vertices is such that the associated - characters are in ASCII ascending order - (2) if two graphs are labelled using the same string xxx, - the output graphs are identical iff there is an - associated-character-preserving isomorphism between them. - If a leading ’-’ is used, as in -f-xxx, the characters are - assigned to the vertices starting at the last vertex, and - the new order of the vertices respects decreasing ASCII order. - - -y Write a 256-bit cryptographic hashcode to stderr. This depends on - the set of isomorphism classes but not their order. It also - depends on -i, -I, -K, -S, -t and -c. - - -i# select an invariant (1 = twopaths, 2 = adjtriang(K), 3 = triples, - 4 = quadruples, 5 = celltrips, 6 = cellquads, 7 = cellquins, - 8 = distances(K), 9 = indsets(K), 10 = cliques(K), 11 = cellcliq(K), - 12 = cellind(K), 13 = adjacencies, 14 = cellfano, 15 = cellfano2, - 16 = refinvar(K)) - - - -I#:# select mininvarlevel and maxinvarlevel (default 1:1) - -K# select invararg (default 3) - - -q suppress auxiliary information - -===== vcolg ====================================================== - -Usage: vcolg [-q] [-u|-T|-o|-O] [-e#|-e#:#] [-m#] [-c#,..,#] [-f#] [infile [outfile]] - - Read graphs or digraphs and colour their vertices in - all possible ways with colours 0,1,2,... . - Isomorphic graphs derived from the same input are suppressed. - If the input graphs are non-isomorphic then the output graphs are also. - - -e# | -e#:# specify a value or range of the total value of the colours - -m# number of available colours (default 2 if -c not given) - -c#,..,# specify the maximum number of vertices of each colour - The total must at least equal the number of vertices in the input. - -d#,..,# minimum vertex degree for each colour (out-degree for digraphs) - -D#,..,# maximum vertex degree for each colour (out-degree for digraphs) - -d and -D can have fewer colours than -m/-c but not more - -f# Use the group that fixes the first # vertices setwise - -T Use a simple text output format (nv ne {col} {v1 v2}) - -o Use sparse6 (undirected) or digraph6 (directed) for output, - provided m=2 and the inputs have no loops. - -O Same as -o but use loops for weight 0, not weight 1 - -u no output, just count them - -q suppress auxiliary information - -===== watercluster2 ====================================================== - -Usage: watercluster2 [ix] [oy] [m] [T] [C] [B] [Z] [S] - Read undirected graphs and orient them in various ways. - -The option ix restricts the maximum indegree to x. -The option oy restricts the maximum outdegree to y. -The default maximum in- and out-degrees are unlimited. -T means: Output directed graphs in T-code -- for details see header -B means: Output directed graphs in binary code -- for details see header -Z means: Output directed graphs in digraph6 code -C means: Do really construct all the directed graphs in memory, - but don’t output them (default) -S means that for each edge only one direction must be chosen -- not both. -Default is that both are allowed - -- so the edge a-b can become a->b AND b->a in the same output graph. -m means: read multicode instead of g6 code - - - - diff --git a/apn/lean/docs/normaliz/LICENSE b/apn/lean/docs/normaliz/LICENSE deleted file mode 100644 index 33214776..00000000 --- a/apn/lean/docs/normaliz/LICENSE +++ /dev/null @@ -1,682 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 3, 29 June 2007 - - Copyright (C) 2007 Free Software Foundation, Inc. - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The GNU General Public License is a free, copyleft license for -software and other kinds of works. - - The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom to -share and change all versions of a program--to make sure it remains free -software for all its users. We, the Free Software Foundation, use the -GNU General Public License for most of our software; it applies also to -any other work released this way by its authors. You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - - To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you have -certain responsibilities if you distribute copies of the software, or if -you modify it: responsibilities to respect the freedom of others. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, receive -or can get the source code. And you must show them these terms so they -know their rights. - - Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - - For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - - Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the manufacturer -can do so. This is fundamentally incompatible with the aim of -protecting users' freedom to change the software. The systematic -pattern of such abuse occurs in the area of products for individuals to -use, which is precisely where it is most unacceptable. Therefore, we -have designed this version of the GPL to prohibit the practice for those -products. If such problems arise substantially in other domains, we -stand ready to extend this provision to those domains in future versions -of the GPL, as needed to protect the freedom of users. - - Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish to -avoid the special danger that patents applied to a free program could -make it effectively proprietary. To prevent this, the GPL assures that -patents cannot be used to render the program non-free. - - The precise terms and conditions for copying, distribution and -modification follow. - - TERMS AND CONDITIONS - - 0. Definitions. - - "This License" refers to version 3 of the GNU General Public License. - - "Copyright" also means copyright-like laws that apply to other kinds of -works, such as semiconductor masks. - - "The Program" refers to any copyrightable work licensed under this -License. Each licensee is addressed as "you". "Licensees" and -"recipients" may be individuals or organizations. - - To "modify" a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of an -exact copy. The resulting work is called a "modified version" of the -earlier work or a work "based on" the earlier work. - - A "covered work" means either the unmodified Program or a work based -on the Program. - - To "propagate" a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - - To "convey" a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user through -a computer network, with no transfer of a copy, is not conveying. - - An interactive user interface displays "Appropriate Legal Notices" -to the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - - 1. Source Code. - - The "source code" for a work means the preferred form of the work -for making modifications to it. "Object code" means any non-source -form of a work. - - A "Standard Interface" means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - - The "System Libraries" of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -"Major Component", in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - - The "Corresponding Source" for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - - The Corresponding Source need not include anything that users -can regenerate automatically from other parts of the Corresponding -Source. - - The Corresponding Source for a work in source code form is that -same work. - - 2. Basic Permissions. - - All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - - You may make, run and propagate covered works that you do not -convey, without conditions so long as your license otherwise remains -in force. You may convey covered works to others for the sole purpose -of having them make modifications exclusively for you, or provide you -with facilities for running those works, provided that you comply with -the terms of this License in conveying all material for which you do -not control copyright. Those thus making or running the covered works -for you must do so exclusively on your behalf, under your direction -and control, on terms that prohibit them from making any copies of -your copyrighted material outside their relationship with you. - - Conveying under any other circumstances is permitted solely under -the conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - - 3. Protecting Users' Legal Rights From Anti-Circumvention Law. - - No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - - When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such circumvention -is effected by exercising rights under this License with respect to -the covered work, and you disclaim any intention to limit operation or -modification of the work as a means of enforcing, against the work's -users, your or third parties' legal rights to forbid circumvention of -technological measures. - - 4. Conveying Verbatim Copies. - - You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - - You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - - 5. Conveying Modified Source Versions. - - You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these conditions: - - a) The work must carry prominent notices stating that you modified - it, and giving a relevant date. - - b) The work must carry prominent notices stating that it is - released under this License and any conditions added under section - 7. This requirement modifies the requirement in section 4 to - "keep intact all notices". - - c) You must license the entire work, as a whole, under this - License to anyone who comes into possession of a copy. This - License will therefore apply, along with any applicable section 7 - additional terms, to the whole of the work, and all its parts, - regardless of how they are packaged. This License gives no - permission to license the work in any other way, but it does not - invalidate such permission if you have separately received it. - - d) If the work has interactive user interfaces, each must display - Appropriate Legal Notices; however, if the Program has interactive - interfaces that do not display Appropriate Legal Notices, your - work need not make them do so. - - A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -"aggregate" if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - - 6. Conveying Non-Source Forms. - - You may convey a covered work in object code form under the terms -of sections 4 and 5, provided that you also convey the -machine-readable Corresponding Source under the terms of this License, -in one of these ways: - - a) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by the - Corresponding Source fixed on a durable physical medium - customarily used for software interchange. - - b) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by a - written offer, valid for at least three years and valid for as - long as you offer spare parts or customer support for that product - model, to give anyone who possesses the object code either (1) a - copy of the Corresponding Source for all the software in the - product that is covered by this License, on a durable physical - medium customarily used for software interchange, for a price no - more than your reasonable cost of physically performing this - conveying of source, or (2) access to copy the - Corresponding Source from a network server at no charge. - - c) Convey individual copies of the object code with a copy of the - written offer to provide the Corresponding Source. This - alternative is allowed only occasionally and noncommercially, and - only if you received the object code with such an offer, in accord - with subsection 6b. - - d) Convey the object code by offering access from a designated - place (gratis or for a charge), and offer equivalent access to the - Corresponding Source in the same way through the same place at no - further charge. You need not require recipients to copy the - Corresponding Source along with the object code. If the place to - copy the object code is a network server, the Corresponding Source - may be on a different server (operated by you or a third party) - that supports equivalent copying facilities, provided you maintain - clear directions next to the object code saying where to find the - Corresponding Source. Regardless of what server hosts the - Corresponding Source, you remain obligated to ensure that it is - available for as long as needed to satisfy these requirements. - - e) Convey the object code using peer-to-peer transmission, provided - you inform other peers where the object code and Corresponding - Source of the work are being offered to the general public at no - charge under subsection 6d. - - A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - - A "User Product" is either (1) a "consumer product", which means any -tangible personal property which is normally used for personal, family, -or household purposes, or (2) anything designed or sold for incorporation -into a dwelling. In determining whether a product is a consumer product, -doubtful cases shall be resolved in favor of coverage. For a particular -product received by a particular user, "normally used" refers to a -typical or common use of that class of product, regardless of the status -of the particular user or of the way in which the particular user -actually uses, or expects or is expected to use, the product. A product -is a consumer product regardless of whether the product has substantial -commercial, industrial or non-consumer uses, unless such uses represent -the only significant mode of use of the product. - - "Installation Information" for a User Product means any methods, -procedures, authorization keys, or other information required to install -and execute modified versions of a covered work in that User Product from -a modified version of its Corresponding Source. The information must -suffice to ensure that the continued functioning of the modified object -code is in no case prevented or interfered with solely because -modification has been made. - - If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - - The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or updates -for a work that has been modified or installed by the recipient, or for -the User Product in which it has been modified or installed. Access to a -network may be denied when the modification itself materially and -adversely affects the operation of the network or violates the rules and -protocols for communication across the network. - - Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - - 7. Additional Terms. - - "Additional permissions" are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - - When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - - Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders of -that material) supplement the terms of this License with terms: - - a) Disclaiming warranty or limiting liability differently from the - terms of sections 15 and 16 of this License; or - - b) Requiring preservation of specified reasonable legal notices or - author attributions in that material or in the Appropriate Legal - Notices displayed by works containing it; or - - c) Prohibiting misrepresentation of the origin of that material, or - requiring that modified versions of such material be marked in - reasonable ways as different from the original version; or - - d) Limiting the use for publicity purposes of names of licensors or - authors of the material; or - - e) Declining to grant rights under trademark law for use of some - trade names, trademarks, or service marks; or - - f) Requiring indemnification of licensors and authors of that - material by anyone who conveys the material (or modified versions of - it) with contractual assumptions of liability to the recipient, for - any liability that these contractual assumptions directly impose on - those licensors and authors. - - All other non-permissive additional terms are considered "further -restrictions" within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - - If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - - Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; -the above requirements apply either way. - - 8. Termination. - - You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - - However, if you cease all violation of this License, then your -license from a particular copyright holder is reinstated (a) -provisionally, unless and until the copyright holder explicitly and -finally terminates your license, and (b) permanently, if the copyright -holder fails to notify you of the violation by some reasonable means -prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - - Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - - 9. Acceptance Not Required for Having Copies. - - You are not required to accept this License in order to receive or -run a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - - 10. Automatic Licensing of Downstream Recipients. - - Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - - An "entity transaction" is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - - You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - - 11. Patents. - - A "contributor" is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's "contributor version". - - A contributor's "essential patent claims" are all patent claims -owned or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, "control" includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - - Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - - In the following three paragraphs, a "patent license" is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To "grant" such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - - If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. "Knowingly relying" means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - - If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - - A patent license is "discriminatory" if it does not include within -the scope of its coverage, prohibits the exercise of, or is -conditioned on the non-exercise of one or more of the rights that are -specifically granted under this License. You may not convey a covered -work if you are a party to an arrangement with a third party that is -in the business of distributing software, under which you make payment -to the third party based on the extent of your activity of conveying -the work, and under which the third party grants, to any of the -parties who would receive the covered work from you, a discriminatory -patent license (a) in connection with copies of the covered work -conveyed by you (or copies made from those copies), or (b) primarily -for and in connection with specific products or compilations that -contain the covered work, unless you entered into that arrangement, -or that patent license was granted, prior to 28 March 2007. - - Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - - 12. No Surrender of Others' Freedom. - - If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey a -covered work so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you may -not convey it at all. For example, if you agree to terms that obligate you -to collect a royalty for further conveying from those to whom you convey -the Program, the only way you could satisfy both those terms and this -License would be to refrain entirely from conveying the Program. - - 13. Use with the GNU Affero General Public License. - - Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - - 14. Revised Versions of this License. - - The Free Software Foundation may publish revised and/or new versions of -the GNU General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - - Each version is given a distinguishing version number. If the -Program specifies that a certain numbered version of the GNU General -Public License "or any later version" applies to it, you have the -option of following the terms and conditions either of that numbered -version or of any later version published by the Free Software -Foundation. If the Program does not specify a version number of the -GNU General Public License, you may choose any version ever published -by the Free Software Foundation. - - If the Program specifies that a proxy can decide which future -versions of the GNU General Public License can be used, that proxy's -public statement of acceptance of a version permanently authorizes you -to choose that version for the Program. - - Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - - 15. Disclaimer of Warranty. - - THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY -OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, -THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM -IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF -ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. Limitation of Liability. - - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS -THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY -GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE -USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF -DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD -PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), -EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF -SUCH DAMAGES. - - 17. Interpretation of Sections 15 and 16. - - If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . - -Also add information on how to contact you by electronic and paper mail. - - If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - - Copyright (C) - This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, your program's commands -might be different; for a GUI interface, you would use an "about box". - - You should also get your employer (if you work as a programmer) or school, -if any, to sign a "copyright disclaimer" for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -. - - The GNU General Public License does not permit incorporating your program -into proprietary programs. If your program is a subroutine library, you -may consider it more useful to permit linking proprietary applications with -the library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. But first, please read -. - - - -As an exception, when this program is distributed through (i) the App Store -by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or (iii) Google Play -by Google Inc., then that store may impose any digital rights management, -device limits and/or redistribution restrictions that are required by its -terms of service. diff --git a/apn/lean/docs/normaliz/normaliz-manual.txt b/apn/lean/docs/normaliz/normaliz-manual.txt deleted file mode 100644 index 6eccbe48..00000000 --- a/apn/lean/docs/normaliz/normaliz-manual.txt +++ /dev/null @@ -1,3604 +0,0 @@ - - -2. Discrete convex geometry by examples -2.1. Terminology -For the precise interpretation of parts of the Normaliz output some terminology is necessary, -but this section can be skipped at first reading, and the user can come back to it when it -becomes necessary. We will give less formal descriptions along the way. The following applies -to rational polyhedra. Algebraic polyhedra are discussed in Section 8. -As pointed out in the introduction, Normaliz “computes” intersections P ∩ L where P is a -rational polyhedron in Rd and L is an affine sublattice of Zd . It proceeds as follows: - (1) If the input is inhomogeneous, then it is homogenized by introducing a homogenizing - coordinate: the polyhedron P is replaced by the cone C(P): it is the closure of R+ (P × - {1}) in Rd+1 . Similarly L is replaced by L - e = Z(L × {1}). In the homogeneous case in - which P is a cone and L is a subgroup of Zd , we set C(P) = P and Le = L. - (2) The computations take place in the efficient lattice - e ∩ RC(P). - E=L - - where RC(P) is the linear subspace generated by C(P). The internal coordinates are - chosen with respect to a basis of E. The efficient cone is - - C = R+ (C(P) ∩ E). - - (3) Inhomogeneous computations are truncated using the dehomogenization (defined im- - plicitly or explicitly). - (4) The final step is the conversion to the original coordinates. Note that we must use the - coordinates of Rd+1 if homogenization has been necessary, simply because some output - vectors may be non-integral otherwise. -Normaliz computes inequalities, equations and congruences defining E and C. The output -contains only those constraints that are really needed. They must always be used jointly: the -equations and congruences define E, and the equations and inequalities define C. Altogether -they define the monoid M = C ∩ E. In the homogeneous case this is the monoid to be com- -puted. In the inhomogeneous case we must intersect M with the dehomogenizing hyperplane -to obtain P ∩ L. -In this section, only pointed cones (and polyhedra with vertices) will be discussed. Nonpointed -cones will be addressed in Section 7.13. - - -2.2. Practical preparations -You may find it comfortable to run Normaliz via the GUI jNormaliz [4]. In the Normaliz -directory open jNormaliz by clicking jNormaliz.jar in the appropriate way. (We assume that -Java is installed on your machine.) In the jNormaliz file dialogue choose one of the input files - - - - Figure 1: jNormaliz - - -in the subdirectory example, say small.in, and press Run. In the console window you can -watch Normaliz at work. Finally inspect the output window for the results. -The menus and dialogues of jNormaliz are self explanatory, but you can also consult the -documentation [4] via the help menu. -Remark The jNormaliz drop down menus do presently not cover all options of Normaliz. But -since all computation goals and algorithmic variants can be set in the input file, there is no -real restriction in using jNormaliz. The only option not reachable by jNormaliz is the output -directory (see Section 6.7). -Moreover, one can, and often will, run Normaliz from the command line. This is fully ex- -plained in Section 6. At this point it is enough to call Normaliz by typing - normaliz -c - -where denotes for the project to be computed. Normaliz will load the file .in. -The option -c makes Normaliz to write a progress report on the terminal. Normaliz writes its -results to .out. -Note that you may have to prefix normaliz by a path name, and must contain a -path to the input file if it is not in the current directory. Suppose the Normaliz directory is the -current directory and we are using a Linux or Mac system. Then - ./normaliz -c example/small - -will run small.in from the directory example. On Windows we must change this to - .\normaliz -c example\small - -The commands given above will run Normaliz with the at most 8 parallel threads. For the very -small examples in this tutorial you may want to add -x=1 to suppress parallelization. For large -examples, you can increase the number of parallel threads by -x= where is the number - - - -of threads that you want to suggest. See Section 6.3. -As long as you don’t specify a computation goal on the command line or in the input file, -Normaliz will use the default computation goals: - -HilbertBasis -HilbertSeries -ClassGroup - -The computation of the Hilbert series requires the explicit or implicit definition of a grading. -Normaliz does only complain that a computation goal cannot be reached if the goal has been -set explicitly. For example, if you say HilbertSeries and there is no grading, an exception -will be thrown and Normaliz terminates, but an output file with the already computed data will -be written. -Note that the spacing in the output files may have changed over time and that not all these -changes may have made their way into this manual. -Normaliz will always print the results that are obtained on the way to the computation goals -and do not require extra effort. -Appendix B helps you to read the console output that you have demanded by the option -c. - - -2.3. A cone in dimension 2 -We want to investigate the cone C = R+ (2, 1) + R+ (1, 3) ⊂ R2 : - - - - - -This cone is defined in the input file 2cone.in: - amb_space 2 - cone 2 - 1 3 - 2 1 - -The input tells Normaliz that the ambient space is R2 , and then a cone with 2 generators is -defined, namely the cone C from above. -The figure indicates the Hilbert basis, and this is our first computation goal. - - - -If you prefer to consider the columns of a matrix as input vectors (or have a matrix in this -format from another system) you can use the input - amb_space 2 - cone transpose 2 - 1 2 - 3 1 - -Note that the number 2 following transpose is now the number of columns. Later on we will -also show the use of formatted matrices. - -2.3.1. The Hilbert basis - -In order to compute the Hilbert basis, we run Normaliz from jNormaliz or by - ./normaliz -c example/2cone - -and inspect the output file: - 4 Hilbert basis elements - 2 extreme rays - 2 support hyperplanes - -Self explanatory so far. - embedding dimension = 2 - rank = 2 (maximal) - external index = 1 - internal index = 5 - original monoid is not integrally closed in chosen lattice - -The embedding dimension is the dimension of the space in which the computation is done. -The rank is the rank of the lattice E (notation as in Section 2.1). In fact, in our example E = Z2 , -and therefore has rank 2. -For subgroups G ⊂ U ⊂ Zd we denote the order of the torsion subgroup of U/G by the index -of G in U. The external index is the index of the lattice E in Zd . In our case E = Zd , and -therefore the external index is 1. Note: the external index is 1 exactly when E is a direct -summand of Zd . -For this example and many others the original monoid is well defined: the generators of the -cone used as input are contained in E. (This need not be the case if E is a proper sublattice of -Zd , and we let the original monoid be undefined in inhomogeneous computations.) Let G be -the subgroup generated by the original monoid. The internal index is the index of G in E. -The original monoid is integrally closed if and only if the it contains the Hilbert basis, and this -is evidently false for our example. We go on. - size of triangulation = 1 - resulting sum of |det|s = 5 - - - - -The primal algorithm of Normaliz relies on a (partial) triangulation. In our case the triangula- -tion consists of a single simplicial cone, and (the absolute value of) its determinant is 5. - No implicit grading found - -If you do not define a grading explicitly, Normaliz tries to find one itself: the grading is defined -if and only if there is a linear form γ on E under which all extreme rays of the efficient cone -C have value 1, and if so, γ is the implicit grading. Such does not exist in our case. -The last information before we come to the vector lists: - rank of class group = 0 - finite cyclic summands: - 5: 1 - -The class group of the monoid M has rank 0, in other words, it is finite. It has one finite cyclic -summand of order 5. -This is the first instance of a multiset of integers displayed as a sequence of pairs - : -Such an entry says: the multiset contains the number with multiplicity . -Now we look at the vector lists (typeset in two columns to save space): - 4 Hilbert basis elements: 2 extreme rays: - 1 1 1 3 - 1 2 2 1 - 1 3 - 2 1 2 support hyperplanes: - -1 2 - 3 -1 - -The support hyperplanes are given by the linear forms (or inner normal vectors): - - −x1 + 2x2 ≥ 0, - 3x1 − x2 ≥ 0. - -If the order is not fixed for some reason, Normaliz sorts vector lists as follows: (1) by degree -if a grading exists and the application makes sense, (2) lexicographically. - - -2.3.2. The cone by inequalities - -Instead by generators, we can define the cone by the inequalities just computed (2cone_ineq.in). -We use this example to show the input of a formatted matrix: - amb_space auto - inequalities - [[-1 2] [3 -1]] - - - - -A matrix of input type inequalities contains homogeneous inequalities. Normaliz can deter- -mine the dimension of the ambient space from the formatted matrix. Therefore we can declare -the ambient space as being “auto determined” (but amb_space 2 is not forbidden). -We get the same result as with 2cone.in except that the data depending on the original monoid -cannot be computed: the internal index and the information on the original monoid are missing -since there is no original monoid. - -2.3.3. The interior - -Now we want to compute the lattice points in the interior of our cone. If the cone C is given -by the inequalities λi (x) ≥ 0 (within aff(C)), then the interior is given by the inequalities -λi (x) > 0. Since we are interested in lattice points, we work with the inequalities λi (x) ≥ 1. -The input file 2cone_int.in says - amb_space 2 - strict_inequalities 2 - -1 2 - 3 -1 - -The strict inequalities encode the conditions - −x1 + 2x2 ≥ 1, - 3x1 − x2 ≥ 1. -This is our first example of inhomogeneous input. -Note that the strict inequalities do not define the interior of the cone as a point set. They define -a (closed) polyhedron with the same lattice points as the interior. - - - - - - -Alternatively we could use the following two equivalent input files, in a more intuitive nota- -tion: - amb_space 2 - constraints 2 - -1 2 > 0 - 3 -1 > 0 - - - - - amb_space 2 - constraints 2 - -1 2 >= 1 - 3 -1 >= 1 - - -There is an even more intuitive way to type the input file using symbolic constraints that we -will introduce in Section 2.6.2. -Normaliz homogenizes inhomogeneous computations by introducing an auxiliary homogeniz- -ing coordinate xd+1 . The polyhedron is obtained by intersecting the homogenized cone with -the hyperplane xd+1 = 1. The recession cone is the intersection with the hyperplane xd+1 = 0. -The recession monoid is the monoid of lattice points in the recession cone, and the set of lattice -points in the polyhedron is represented by its system of module generators over the recession -monoid. -Note that the homogenizing coordinate serves as the denominator for rational vectors. In our -example the recession cone is our old friend that we have already computed, and therefore we -need not comment on it. - 2 module generators - 4 Hilbert basis elements of recession monoid - 1 vertices of polyhedron - 2 extreme rays of recession cone - 3 support hyperplanes of polyhedron (homogenized) - - - embedding dimension = 3 - affine dimension of the polyhedron = 2 (maximal) - rank of recession monoid = 2 - - -The only surprise may be the embedding dimension: Normaliz always takes the dimension -of the space in which the computation is done. It is the number of components of the output -vectors. Because of the homogenization it has increased by 1. - size of triangulation = 1 - resulting sum of |det|s = 25 - -In this case the homogenized cone has stayed simplicial, but the determinant has changed. - dehomogenization: - 0 0 1 - -The dehomogenization is the linear form δ on the homogenized space that defines the hyper- -planes from which we get the polyhedron and the recession cone by the equations δ (x) = 1 -and δ (x) = 0, respectively. It is listed since one can also work with a user defined dehomoge- -nization. - module rank = 1 - -This is the rank of the module of lattice points in the polyhedron over the recession monoid. - - - -In our case the module is an ideal, and so the rank is 1. -The output of inhomogeneous computations is always given in homogenized form. The last -coordinate is the value of the dehomogenization on the listed vectors, 1 on the module gener- -ators, 0 on the vectors in the recession monoid: - 2 module generators: 4 Hilbert basis elements of recession monoid: - 1 1 1 1 1 0 - 1 2 1 1 2 0 - 1 3 0 - 2 1 0 - -The module generators are (1, 1) and (1, 2). - 1 vertices of polyhedron: - 3 4 5 - -Indeed, the polyhedron has a single vertex, namely (3/5, 4/5). - 2 extreme rays of recession cone: 3 support hyperplanes of polyhedron (homogenized): - 1 3 0 -1 2 -1 - 2 1 0 0 0 1 - 3 -1 -1 - -Two support hyperplanes are exactly those that we have used to define the polyhedron – and -it has only 2. But Normaliz always outputs the support hyperplanes that are needed for the -cone that one obtains by homogenizing the polyhedron, as indicated by “homogenized”. The -homogenizing variable is always ≥ 0. In this case the support hyperplane (0, 0, 1) is essential -for the description of the cone. Note that it need not always appear. - - -2.4. A lattice polytope -The file polytope.in contains - - amb_space 4 - polytope 4 - 0 0 0 - 2 0 0 - 0 3 0 - 0 0 5 - -This is a good place to mention that Normaliz also accepts matrices (and vectors) in sparse -format: - amb_space 4 - polytope 4 sparse - ; - 1:2; - - - - - 2:3; - 3:5; - - -Each input row, concluded by ;, lists the indices and the corresponding nonzero values in that -row of the matrix. -The Ehrhart monoid of the integral polytope with the 4 vertices - - (0, 0, 0) , (2, 0, 0) , (0, 3, 0) and (0, 0, 5) - -in R3 is to be computed. The generators of the Ehrhart monoid are obtained by attaching a -further coordinate 1 to the vertices, and this explains amb_space 4. In fact, the input type -polytope is not only a convenient version of - - cone 4 - 0 0 0 1 - 2 0 0 1 - 0 3 0 1 - 0 0 5 1 - -It also sets the he grading to be the last coordinate. See 4.12 below for general information on -gradings. -Running normaliz produces the file polytope.out: - 19 Hilbert basis elements - 18 lattice points in polytope (Hilbert basis elements of degree 1) - 4 extreme rays - 4 support hyperplanes - - - embedding dimension = 4 - rank = 4 (maximal) - external index = 1 - internal index = 30 - original monoid is not integrally closed in chosen lattice - -Perhaps a surprise: the lattice points of the polytope do not yield all Hilbert basis elements. - size of triangulation = 1 - resulting sum of |det|s = 30 - -Nothing really new so far. The grading appears in the output file: - grading: - 0 0 0 1 - - - degrees of extreme rays: - 1: 4 - -Again we encounter the notation : : we have 4 extreme rays, all of degree 1. - - - - Hilbert basis elements are not of degree 1 - -We knew this already: the polytope is not integrally closed as defined in [11]. Now we see the -enumerative data defined by the grading: - multiplicity = 30 - - - Hilbert series: - 1 14 15 - denominator with 4 factors: - 1: 4 - - - degree of Hilbert Series as rational function = -2 - - - Hilbert polynomial: - 1 4 8 5 - with common denominator = 1 - -The polytope has Z3 -normalized volume 30 as indicated by the multiplicity (see Section 7.1.1 -for a discussion of volumes and multiplicities). The Hilbert (or Ehrhart) function counts the -lattice points in kP, k ∈ Z+ . The corresponding generating function is a rational function H(t). -For our polytope it is - 1 + 14t + 15t 2 - . - (1 − t)4 -The denominator is given in multiset notation: 1: 4 say that the factor (1 − t 1 ) occurs with -multiplicity 4. -The Ehrhart polynomial (again we use a more general term in the output file) of the polytope -is - p(k) = 1 + 4k + 8k2 + 5k3 . -In our case it has integral coefficients, a rare exception. Therefore one usually needs a denom- -inator. -Everything that follows has already been explained. - rank of class group = 0 - finite cyclic summands: - 30: 1 - - - *********************************************************************** - - 18 lattice points in polytope (Hilbert basis elements of degree 1): - 0 0 0 1 - ... - 2 0 0 1 - - - - - 1 further Hilbert basis elements of higher degree: - 1 2 4 2 - - - 4 extreme rays: 4 support hyperplanes: - 0 0 0 1 -15 -10 -6 30 - 0 0 5 1 0 0 1 0 - 0 3 0 1 0 1 0 0 - 2 0 0 1 1 0 0 0 - -The support hyperplanes give us a description of the polytope by inequalities: it is the solution -of the system of the 4 inequalities - - x3 ≥ 0 , x2 ≥ 0 , x1 ≥ 0 and 15x1 + 10x2 + 6x3 ≤ 30 . - -2.4.1. Only the lattice points - -Suppose we want to compute only the lattice points in our polytope. In the language of -graded monoids these are the degree 1 elements, and so we add Deg1Elements to our input file -(polytope_deg1.in): - amb_space 4 - polytope 4 - 0 0 0 - 2 0 0 - 0 3 0 - 0 0 5 - Deg1Elements - /* This is our first explicit computation goal*/ - -We have used this opportunity to include a comment in the input file. The computation of -lattice points in a polytope will be taken up again in Sections 2.13 and 7.2. -We lose all information on the Hilbert series, and from the Hilbert basis we only retain the -degree 1 elements. - - -2.5. A rational polytope -The type polytope can (now) be used for rational polytopes as well. - - - - -We want to investigate the Ehrhart series of the triangle P with vertices - (1/2, 1/2), (−1/3, −1/3), (1/4, −1/2). -For this example the procedure above yields the input file rational.in: - amb_space 3 - polytope 3 - 1/2 1/2 - -1/3 -1/3 - 1/4 -1/2 - HilbertSeries - - -From the output file we only list the data of the Ehrhart series. - multiplicity = 5/8 - multiplicity (float) = 0.625 - - - Hilbert series: - 1 0 0 3 2 -1 2 2 1 1 1 1 2 - denominator with 3 factors: - 1: 1 2: 1 12: 1 - - - degree of Hilbert Series as rational function = -3 - - - Hilbert series with cyclotomic denominator: - -1 -1 -1 -3 -4 -3 -2 - cyclotomic denominator: - 1: 3 2: 2 3: 1 4: 1 - - - Hilbert quasi-polynomial of period 12: - 0: 48 28 15 7: 23 22 15 - 1: 11 22 15 8: 16 28 15 - 2: -20 28 15 9: 27 22 15 - 3: 39 22 15 10: -4 28 15 - 4: 32 28 15 11: 7 22 15 - 5: -5 22 15 with common denominator = 48 - 6: 12 28 15 - -The multiplicity is a rational number. Since in dimension 2 the normalized area (of full- -dimensional polytopes) is twice the Euclidean area, we see that P has Euclidean area 5/16. -If the multiplicity is not integral, we also print it in floating point format, This is certainly -superfluous for a fraction like 5/8, but very handy if the numerator and the denominator have -many digits. -Unlike in the case of a lattice polytope, there is no canonical choice of the denominator of the -Ehrhart series. Normaliz gives it in 2 forms. In the first form the numerator polynomial is - 1 + 3t 3 + 2t 4 − t 5 + 2t 6 + 2t 7 + t 8 + t 9 + t 10 + t 11 + 2t 12 - - - -and the denominator is - (1 − t)(1 − t 2 )(1 − t 12 ). -As a rational function, H(t) has degree −3. This implies that 3P is the smallest integral -multiple of P that contains a lattice point in its interior. -Normaliz gives also a representation as a quotient of coprime polynomials with the denomi- -nator factored into cyclotomic polynomials. In this case we have - - 1 + t + t 2 + t 3 + 4t 4 + 3t 5 + 2t 6 - H(t) = − - ζ13 ζ22 ζ3 ζ4 - -where ζi is the i-th cyclotomic polynomial (ζ1 = t − 1, ζ2 = t + 1, ζ3 = t 2 +t + 1, ζ4 = t 2 + 1). -Normaliz transforms the representation with cyclotomic denominator into one with denomi- -nator of type (1 − t e1 ) · · · (1 − t er ), r = rank, by choosing er as the least common multiple of -all the orders of the cyclotomic polynomials appearing, er−1 as the lcm of those orders that -have multiplicity ≥ 2 etc. -There are other ways to form a suitable denominator with 3 factors 1 − t e , for example g(t) = -(1 − t 2 )(1 − t 3 )(1 − t 4 ) = −ζ13 ζ22 ζ3 ζ4 . Of course, g(t) is the optimal choice in this case. -However, P is a simplex, and in general such optimal choice may not exist. We will explain -the reason for our standardization below. -Let p(k) be the number of lattice points in kP. Then p(k) is a quasipolynomial: - - p(k) = p0 (k) + p1 (k)k + · · · + pr−1 (k)kr−1 , - -where the coefficients depend on k, but only to the extent that they are periodic of a certain -period π ∈ N. In our case π = 12 (the lcm of the orders of the cyclotomic polynomials). -The table giving the quasipolynomial is to be read as follows: The first column denotes the -residue class j modulo the period and the corresponding line lists the coefficients pi ( j) in -ascending order of i, multiplied by the common denominator. So - 7 5 - p(k) = 1 + k + k2 , k ≡ 0 (12), - 12 16 -etc. The leading coefficient is the same for all residue classes and equals the Euclidean volume -(in this case). -Our choice of denominator for the Hilbert series is motivated by the following fact: ei is the -common period of the coefficients pr−i , . . . , pr−1 . The user should prove this fact or at least -verify it by several examples. -Especially in the case of a simplex the representation of the Hilbert series shown so far may -not be the expected one. In fact, there is a representation in which the exponents of t in the -denominator are the degrees of the integral extreme generators. So one would expect the -denominator to be (1 − t 2 )(1 − t 3 )(1 − t 4 ) in our case. The generalization to the nonsimplicial -case uses the degrees of a homogeneous system of parameters (see [11, p. 200]). Normaliz -can compute such a denominator if the computation goal - - - -HSOP -is set (rationalHSOP.in): - Hilbert series (HSOP): - 1 1 1 3 4 3 2 - denominator with 3 factors: - 2: 1 3: 1 4: 1 - -Note that the degrees of the elements in a homogeneous system of parameters are by no means -unique and that there is no optimal choice in general. To find a suitable sequence of degrees -Normaliz must compute the face lattice of the cone to some extent. Therefore be careful not -to ask for HSOP if the cone has many support hyperplanes. - - -2.5.1. The series with vertices? - -It is tempting to define the polytope by the input type vertices. This choice makes the com- -putation inhomogeneous, a mode that is mainly meant for (potentially) unbounded polyhedra. -But it can be used for polytopes as well, and with this input type you can compute all of the data -that we have seen above. You must ask for the EhrhartSeries instead of the HilbertSeries. -The file rational_inhom.in is - amb_space 2 - vertices 3 - 1/2 1/2 1 - -1/3 -1/3 1 - 1/4 -1/2 1 - EhrhartSeries - -Nevertheless, there is also use for HilbertSeries in the inhomogeneous case. But then the -grading must be defined on the affine space of the polytope (and not on the cone over the -polytope). See Sections 7.1 and 7.10.2. - - -2.5.2. The rational polytope by inequalities - -We extract the support hyperplanes of our polytope from the output file and use them as input -(poly_ineq.in): - amb_space 3 - inequalities 3 - -8 2 3 - 1 -1 0 - 2 7 3 - grading - unit_vector 3 - HilbertSeries - - - - -At this point we have to help Normaliz because it has no way to guess that we want to inves- -tigate the polytope defined by the inequalities and the choice x3 = 1. This is achieved by the -specification of the grading that maps every vector to its third coordinate. -This is the first time that we used the shortcut unit_vector which represents the n-th unit -vector en ∈ Rd and is only allowed for input types which require a single vector. -These data tell us that the polytope, as a subset of R2 , is defined by the inequalities - - −8x1 + 2x2 + 3 ≥ 0, - x1 − x2 + 0 ≥ 0, - 2x1 + 7x2 + 3 ≥ 0. - -These inequalities are inhomogeneous, but we are using the homogeneous input type inequalities -which amounts to introducing the grading variable x3 as explained above. -The inequalities as written above look somewhat artificial. It is certainly more natural to write -them in the form - - 8x1 − 2x2 ≤ 3, - x1 − x2 ≥ 0, - 2x1 + 7x2 ≥ −3. - -and for the direct transformation into Normaliz input we have introduced the type hom_constraints. -The prefix hom indicates that we want homogeneous inequalities whereas plain constraints -that we have already seen in Section 2.3.3 gives inhomogeneous inequalities. The file poly_hom_const.in -contains - amb_space 3 - hom_constraints 3 - 8 -2 <= 3 - 1 -1 >= 0 - 2 7 >= -3 - grading - unit_vector 3 - HilbertSeries - -You can of course also switch to inhomogeneous input using inhom_inequalities or constraints -in the same way as polytope can be replaced by vertices. - - -2.6. Magic squares -Suppose that you are interested in the following type of “square” - - x1 x2 x3 - x4 x5 x6 - x7 x8 x9 - - - -and the problem is to find nonnegative values for x1 , . . . , x9 such that the 3 numbers in all rows, -all columns, and both diagonals sum to the same constant M . Sometimes such squares are -called magic and M is the magic constant. This leads to a linear system of equations - - x1 + x2 + x3 = x4 + x5 + x6 ; - x1 + x2 + x3 = x7 + x8 + x9 ; - x1 + x2 + x3 = x1 + x4 + x7 ; - x1 + x2 + x3 = x2 + x5 + x8 ; - x1 + x2 + x3 = x3 + x6 + x9 ; - x1 + x2 + x3 = x1 + x5 + x9 ; - x1 + x2 + x3 = x3 + x5 + x7 . - - -This system is encoded in the file 3x3magic.in: - amb_space 9 - equations 7 - 1 1 1 -1 -1 -1 0 0 0 - 1 1 1 0 0 0 -1 -1 -1 - 0 1 1 -1 0 0 -1 0 0 - 1 0 1 0 -1 0 0 -1 0 - 1 1 0 0 0 -1 0 0 -1 - 0 1 1 0 -1 0 0 0 -1 - 1 1 0 0 -1 0 -1 0 0 - grading - sparse 1:1 2:1 3:1; - -The input type equations represents homogeneous equations. The first equation reads - - x1 + x2 + x3 − x4 − x5 − x6 = 0, - -and the other equations are to be interpreted analogously. The magic constant is a natural -choice for the grading. It is given in sparse form, equivalent to the dense form - grading - 1 1 1 0 0 0 0 0 0 - -It seems that we have forgotten to define the cone. This may indeed be the case, but doesn’t -matter: if there is no input type that defines a cone, Normaliz chooses the positive orthant, and -this is exactly what we want in this case. -The output file contains the following: - 5 Hilbert basis elements - 5 lattice points in polytope (Hilbert basis elements of degree 1) - 4 extreme rays - 4 support hyperplanes - - - - - embedding dimension = 9 - rank = 3 - external index = 1 - - - size of triangulation = 2 - resulting sum of |det|s = 4 - - - grading: - 1 1 1 0 0 0 0 0 0 - with denominator = 3 - - -The input degree is the magic constant. However, as the denominator 3 shows, the magic -constant is always divisible by 3, and therefore the effective degree is M /3. This degree is -used for the multiplicity, the Hilbert series, and the Hilbert basis elements of degree 1, and -other date depending on the degree. -By introducing the grading denominator, Normaliz has changed the grading defined by you, -and you may not like this. There is a way out: add the option NoGradingDenom. We will -discuss the consequences below. - degrees of extreme rays: - 1: 4 - - - Hilbert basis elements are of degree 1 - -This was not to be expected (and is no longer true for 4 × 4 squares). - multiplicity = 4 - - - Hilbert series: - 1 2 1 - denominator with 3 factors: - 1: 3 - - - degree of Hilbert Series as rational function = -1 - - - Hilbert polynomial: - 1 2 2 - with common denominator = 1 - -The Hilbert series is - 1 + 2t + t 2 - . - (1 − t)3 -The Hilbert polynomial is - P(k) = 1 + 2k + 2k2 , -and after substituting M /3 for k we obtain the number of magic squares of magic constant - - - -M , provided 3 divides M . (If 3 ∤ M , there is no magic square of magic constant M .) - rank of class group = 1 - finite cyclic summands: - 2: 2 - -So the class group is Z ⊕ (Z/2Z)2 . - 5 lattice points in polytope (Hilbert basis elements of degree 1): - 0 2 1 2 1 0 1 0 2 - 1 0 2 2 1 0 0 2 1 - 1 1 1 1 1 1 1 1 1 - 1 2 0 0 1 2 2 0 1 - 2 0 1 0 1 2 1 2 0 - - - 0 further Hilbert basis elements of higher degree: - -The 5 elements of the Hilbert basis represent the magic squares - - 2 0 1 1 0 2 1 1 1 1 2 0 0 2 1 - 0 1 2 2 1 0 1 1 1 0 1 2 2 1 0 - 1 2 0 0 2 1 1 1 1 2 0 1 1 0 2 - -All other solutions are linear combinations of these squares with nonnegative integer coeffi- -cients. One of these 5 squares is clearly in the interior: - 4 extreme rays: 4 support hyperplanes: - 0 2 1 2 1 0 1 0 2 -2 -1 0 0 4 0 0 0 0 - 1 0 2 2 1 0 0 2 1 0 -1 0 0 2 0 0 0 0 - 1 2 0 0 1 2 2 0 1 0 1 0 0 0 0 0 0 0 - 2 0 1 0 1 2 1 2 0 2 1 0 0 -2 0 0 0 0 - -These 4 support hyperplanes cut out the cone generated by the magic squares from the linear -subspace they generate. Only one is reproduced as a sign inequality. This is due to the fact that -the linear subspace has submaximal dimension and there is no unique lifting of linear forms -to the full space. - 6 equations: 3 basis elements of generated lattice: - 1 0 0 0 0 1 -2 -1 1 1 0 -1 -2 0 2 1 0 -1 - 0 1 0 0 0 1 -2 0 0 0 1 -1 -1 0 1 1 -1 0 - 0 0 1 0 0 1 -1 -1 0 0 0 3 4 1 -2 -1 2 2 - 0 0 0 1 0 -1 2 0 -2 - 0 0 0 0 1 -1 1 0 -1 - 0 0 0 0 0 3 -4 -1 2 - -So one of our equations has turned out to be superfluous (why?). Note that also the equations -are not reproduced exactly. Finally, Normaliz lists a basis of the efficient lattice E generated -by the magic squares. - - - - -Note that the equations and the lattice basis are not uniquely determined. We transform their -matrices into reduced row echelon form to force unique output files. - - -2.6.1. Blocking the grading denominator - -As mentioned above, one can block the grading denominator and force Normaliz to use the -input grading. For the magic squares we augment the input file as follows (3x3magicNGD.in): - amb_space 9 - equations 7 - 1 1 1 -1 -1 -1 0 0 0 - ... - 1 1 0 0 -1 0 -1 0 0 - grading - sparse 1:1 2:1 3:1; - NoGradingDenom - -The consequences: - grading: - 1 1 1 0 0 0 0 0 0 - - - degrees of extreme rays: - 3: 4 - - - multiplicity = 4/9 - multiplicity (float) = 0.444444444444 - - - Hilbert series: - 1 0 0 2 0 0 1 - denominator with 3 factors: - 3: 3 - - - degree of Hilbert Series as rational function = -3 - - - The numerator of the Hilbert series is symmetric. - - - Hilbert series with cyclotomic denominator: - -1 0 0 -2 0 0 -1 - cyclotomic denominator: - 1: 3 3: 3 - - - Hilbert quasi-polynomial of period 3: - 0: 9 6 2 - 1: 0 0 0 - 2: 0 0 0 - with common denominator = 9 - - - - - rank of class group = 1 - finite cyclic summands: - 2: 2 - - - *********************************************************************** - - 0 lattice points in polytope (Hilbert basis elements of degree 1): - -It is easy to relate the data with the grading denominator to those without. You must decide -yourself what you prefer. One aspect is whether one prefers intrinsic data (with grading de- -nominator) to extrinsic ones that depend on the embedding (without the grading denominator). -We will discuss the topic again in Section 7.1. - -2.6.2. With even corners - -We change our definition of magic square by requiring that the entries in the 4 corners are all -even. Then we have to augment the input file by the following (3x3magiceven.in): - congruences 4 sparse - 1:1 10:2; - 3:1 10:2; - 7:1 10:2; - 9:1 10:2; - -This sparse form is equivalent to the dense form - congruences 4 - 1 0 0 0 0 0 0 0 0 2 - 0 0 1 0 0 0 0 0 0 2 - 0 0 0 0 0 0 1 0 0 2 - 0 0 0 0 0 0 0 0 1 2 - -The first 9 entries in each row represent the coefficients of the coordinates in the homogeneous -congruences, and the last is the modulus: - - x1 ≡ 0 mod 2 - -is the first congruence etc. -We could also define these congruences as symbolic constraints: - constraints 4 symbolic - x[1] ~ 0(2); - x[3] ~ 0(2); - x[7] ~ 0(2); - x[9] ~ 0(2); - -The output changes accordingly: - - - - 9 Hilbert basis elements - 0 lattice points in polytope (Hilbert basis elements of degree 1) - 4 extreme rays - 4 support hyperplanes - - - embedding dimension = 9 - rank = 3 - external index = 4 - - - size of triangulation = 2 - resulting sum of |det|s = 8 - - - grading: - 1 1 1 0 0 0 0 0 0 - with denominator = 3 - - - degrees of extreme rays: - 2: 4 - - - multiplicity = 1 - - - Hilbert series: - 1 -1 3 1 - denominator with 3 factors: - 1: 1 2: 2 - - - degree of Hilbert Series as rational function = -2 - - - Hilbert series with cyclotomic denominator: - -1 1 -3 -1 - cyclotomic denominator: - 1: 3 2: 2 - - - Hilbert quasi-polynomial of period 2: - 0: 2 2 1 - 1: -1 0 1 - with common denominator = 2 - - -After the extensive discussion in Section 2.5 it should be easy for you to write down the Hilbert -series and the Hilbert quasipolynomial. (But keep in mind that the grading has a denominator.) - rank of class group = 1 - finite cyclic summands: - 4: 2 - - - *********************************************************************** - - - - - 0 lattice points in polytope (Hilbert basis elements of degree 1): - - - 9 further Hilbert basis elements of higher degree: - ... - - - 4 extreme rays: - 0 4 2 4 2 0 2 0 4 - 2 0 4 4 2 0 0 4 2 - 2 4 0 0 2 4 4 0 2 - 4 0 2 0 2 4 2 4 0 - -We have listed the extreme rays since they have changed after the introduction of the congru- -ences, although the cone has not changed. The reason is that Normaliz always chooses the -extreme rays from the efficient lattice E. - 4 support hyperplanes: - ... - - - 6 equations: - ... 3 basis elements of generated lattice: - 1 0 -1 -2 0 2 1 0 -1 - 2 congruences: 0 1 -1 -1 0 1 1 -1 0 - 1 0 0 0 0 0 0 0 0 2 0 0 3 4 1 -2 -1 2 2 - 0 1 0 0 1 0 0 0 0 2 - -The rank of the lattice has of course not changed, but after the introduction of the congruences -the basis has changed. - -2.6.3. The lattice as input - -It is possible to define the lattice by generators. We demonstrate this for the magic squares -with even corners. The lattice has just been computed (3x3magiceven_lat.in): - amb_space 9 - lattice 3 - 0 1 2 3 1 -1 0 1 2 - 2 -1 2 1 1 1 0 3 0 - 0 3 0 1 1 1 2 -1 2 - grading - 1 1 1 0 0 0 0 0 0 - - -It produces the same output as the version starting from equations and congruences. -lattice has a variant that takes the saturation of the sublattice generated by the input vectors -(3x3magic_sat.in): - amb_space 9 - - - - - saturation 3 - 0 1 2 3 1 -1 0 1 2 - 2 -1 2 1 1 1 0 3 0 - 0 3 0 1 1 1 2 -1 2 - grading - 1 1 1 0 0 0 0 0 0 - - -Clearly, we remove the congruences by this choice and arrive at the output of 3x3magic.in. - - -2.7. Decomposition in a numerical semigroup -Let S = ⟨6, 10, 15⟩, the numerical semigroup generated by 6, 10, 15. How can 97 be written as -a sum in the generators? -In other words: we want to find all nonnegative integral solutions to the equation - 6x1 + 10x2 + 15x3 = 97. - -Input (NumSemi.in): - - amb_space 3 - constraints 1 symbolic - 6x[1] + 10x[2] + 15x[3] = 97; - - -The equation cuts out a triangle from the positive orthant. -The set of solutions is a module over the monoid M of solutions of the homogeneous equation -6x1 + 10x2 + 15x3 = 0. So M = 0 in this case. - 6 lattice points in polytope (module generators): - 2 1 5 1 - 2 4 3 1 - 2 7 1 1 - 7 1 3 1 - 7 4 1 1 - 12 1 1 1 - - - 0 Hilbert basis elements of recession monoid: - -The last line is as expected, and the 6 lattice points (or module generators) are the goal of the -computation. -Normaliz is smart enough to recognize that it must compute the lattice points in a polygon, -and does exactly this. You can recognize it in the console output: Normaliz 3.11.0 has used -the project-and-lift algorithm. We will discuss it further in Section 2.13 and Section 7.2.1. -For those who like to play: add the option --NoProjection to the command line. Then the -terminal output will change; Normaliz computes the lattice points as a truncated Hilbert basis -via a triangulation (only one simplicial cone in this case). - - - -2.8. A job for the dual algorithm -We increase the size of the magic squares to 5 × 5. Normaliz can do the same computation -as for 3 × 3 squares, but this will take some minutes. Suppose we are only interested in the -Hilbert basis, we should use the dual algorithm for this example. (The dual algorithm goes -back to Pottier [34].) The input file is 5x5dual.in: - amb_space 25 - equations 11 - 1 1 1 1 1 -1 -1 -1 -1 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 - ... - 1 1 1 1 0 0 0 0 -1 0 0 0 -1 0 0 0 -1 0 0 0 -1 0 0 0 0 - grading - 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 - HilbertBasis - - -The input file does not say anything about the dual algorithm mentioned in the section title. -With this input it is chosen automatically. See Section 7.5 for a discussion of when this -happens. But you can insist on the dual algorithm by adding DualMode to the input (or -d to -the command line). Or, if you want to compare it to the primal algorithm add PrimalMode (or --P to the command line). -The Hilbert basis contains 4828 elements, too many to be listed here. -With the file 5x5.in you can compute the Hilbert basis and the Hilbert series, and the latter -with HSOP: - Hilbert series (HSOP): - 1 15 356 4692 36324 198467 ... 198467 36324 4692 356 15 1 - denominator with 15 factors: - 1: 5 2: 3 6: 2 12: 1 60: 2 420: 1 1260: 1 - - - degree of Hilbert Series as rational function = -5 - - - The numerator of the Hilbert Series is symmetric. - -In view of the length of the numerator of the Hilbert series it may be difficult to observe the -symmetry. So Normaliz does it for you. The symmetry shows that the monoid is Gorenstein, -but if you are only interested in the Gorenstein property, there is a much faster way to check it -(see Section 7.7). -The size 6 × 6 is out of reach for the Hilbert series, but the Hilbert basis can be computed (in -the automatically chosen dual mode). It takes some hours. - - - - -2.9. A dull polyhedron -We want to compute the polyhedron defined by the inequalities - - ξ2 ≥ −1/2, - ξ2 ≤ 3/2, - ξ2 ≤ ξ1 + 3/2. - -They are contained in the input file InhomIneq.in: - amb_space 2 - constraints 3 - 0 1 >= -1/2 - 0 1 <= 3/2 - -1 1 <= 3/2 - grading - unit_vector 1 - FVector - -The grading says that we want to count points by the first coordinate, namely along the green -lines: - - - - -It yields the output - 2 module generators - 1 Hilbert basis elements of recession monoid - 2 vertices of polyhedron - 1 extreme rays of recession cone - 3 support hyperplanes of polyhedron (homogenized) - - - f-vector: - 1 2 3 1 - -The empty set is the intersection of all facets, and this gives the first entry 1. Then we have 2 -vertices, 3 edges, and finally the full polyhedron. -The out put continues: - embedding dimension = 3 - affine dimension of the polyhedron = 2 (maximal) - rank of recession monoid = 1 - - - - - size of triangulation = 1 - resulting sum of |det|s = 8 - - - dehomogenization: - 0 0 1 - - - grading: - 1 0 0 - - -The interpretation of the grading requires some care in the inhomogeneous case. We have -extended the input grading vector by an entry 0 to match the embedding dimension. For the -computation of the degrees of lattice points in the ambient space you can either use only the -first 2 coordinates or take the full scalar product of the point in homogenized coordinates and -the extended grading vector. - module rank = 2 - multiplicity = 2 - - -The module rank is 2 in this case since we have two “layers” in the solution module that are -parallel to the recession monoid. This is of course also reflected in the Hilbert series. - Hilbert series: - 1 1 - denominator with 1 factors: - 1: 1 - - - shift = -1 - -We haven’t seen a shift yet. It is always printed (necessarily) if the Hilbert series does not start -in degree 0. In our case it starts in degree −1 as indicated by the shift −1. We thus get the -Hilbert series - t +t t −1 + 1 - t −1 = . - 1−t 1−t -Note: We used the opposite convention for the shift in Normaliz 2. -Note that the Hilbert (quasi)polynomial is always computed for the unshifted monoid defined -by the input data. (This was different in previous versions of Normaliz.) - degree of Hilbert Series as rational function = -1 - - - Hilbert polynomial: - 2 - with common denominator = 1 - - - *********************************************************************** - - 2 module generators: - -1 0 1 - - - - - 0 1 1 - - - 1 Hilbert basis elements of recession monoid: - 1 0 0 - - - 2 vertices of polyhedron: - -4 -1 2 - 0 3 2 - - - 1 extreme rays of recession cone: - 1 0 0 - - - 3 support hyperplanes of polyhedron (homogenized): - 0 -2 3 - 0 2 1 - 2 -2 3 - -The dual algorithm that was used in Section 2.8 can also be applied to inhomogeneous com- -putations. We would of course loose the Hilbert series. In certain cases it may be preferable -to suppress the computation of the vertices of the polyhedron if you are only interested in the -integer points; see Section 5.6. - - -2.9.1. Defining it by generators - -If the polyhedron is given by its vertices and the recession cone, we can define it by these data -(InhomIneq_gen.in): - amb_space 2 - vertices 2 - -4 -1 2 - 0 3 2 - cone 1 - 1 0 - grading - unit_vector 1 - -The output is identical to the version starting from the inequalities. - - -2.10. The Condorcet paradox -In social choice elections each of the k voters picks a linear preference order of the n candi- -dates. There are n! such orders. The election result is the vector (x1 , . . . , xN ), N = n!, in which -xi is the number of voters that have chosen the i-th preference order in, say, lexicographic enu- -meration of these orders. (Thus x1 + · · · + xN = k.) In the following we assume the impartial -anonymous culture according to which every election result has the same probability if the - - - -number of voters is fixed. - -We say that candidate A beats candidate B if the majority of the voters prefers A to B. As the -Marquis de Condorcet (and others) observed, “beats” is not transitive, and an election may -exhibit the Condorcet paradox: there is no Condorcet winner. (See [19] and the references -given there for more information.) -We want to find the probability for k → ∞ that there is a Condorcet winner for n = 4 candidates. -The event that A is the Condorcet winner can be expressed by linear inequalities on the election -outcome (a point in 24-space). The wanted probability is the lattice normalized volume of the -polytope cut out by the inequalities at k = 1. The file Condorcet.in: - amb_space 24 - inequalities 3 - 1 1 1 1 1 1 -1 -1 -1 -1 -1 -1 1 1 -1 -1 1 -1 1 1 -1 -1 1 -1 - 1 1 1 1 1 1 1 1 -1 -1 1 -1 -1 -1 -1 -1 -1 -1 1 1 1 -1 -1 -1 - 1 1 1 1 1 1 1 1 1 -1 -1 -1 1 1 1 -1 -1 -1 -1 -1 -1 -1 -1 -1 - nonnegative - total_degree - Multiplicity - - -The first inequality expresses that A beats B, the second and the third say that A beats C and -D. (So far we do not exclude ties, and they need not be excluded for probabilities as k → ∞.) -In addition to these inequalities we must restrict all variables to nonnegative values, and this -is achieved by adding the attribute nonnegative. The grading is set by total_degree. It -replaces the grading vector with 24 entries 1. Finally Multiplicity sets the computation -goal. -From the output file we only mention the quantity we are out for: - multiplicity = 1717/8192 - multiplicity (float) = 0.209594726562 - -Since there are 4 candidates, the probability for the existence of a Condorcet winner is 1717/2048 = -0.209595. -We can refine the information on the Condorcet paradox by computing the Hilbert series. -Either we delete Multiplicity from the input file or, better, we add --HilbertSeries (or -simply -q) on the command line. The result: - Hilbert series: - 1 5 133 363 4581 8655 69821 100915 ... 12346 890 481 15 6 - denominator with 24 factors: - 1: 1 2: 14 4: 9 - - - degree of Hilbert Series as rational function = -25 - -If your executable of Normaliz was built with CoCoALib (see Section 12), for example the -executables for Linux or Mac OS from our distribution or in the Docker image, it uses sym- - - - -metrization for the computation of the Hilbert series. If not, then simply disregard any remark -on symmetrization. Everything runs very quickly also without it. -If symmetrization has been used, you will also find a file Condorcet.symm.out in your direc- -tory. It contains the data computed for the symmetrization. You need not care at this point. -We take continue the discussion of symmetrization in Section 7.8. - - -2.10.1. Excluding ties - -Now we are more ambitious and want to compute the Hilbert series for the Condorcet para- -dox, or more precisely, the number of election outcomes having A as the Condorcet winner -depending on the number k of voters. Moreover, as it is customary in social choice theory, we -want to exclude ties. The input file changes to CondorcetSemi.in: - amb_space 24 - excluded_faces 3 - 1 1 1 1 1 1 -1 -1 -1 -1 -1 -1 1 1 -1 -1 1 -1 1 1 -1 -1 1 -1 - 1 1 1 1 1 1 1 1 -1 -1 1 -1 -1 -1 -1 -1 -1 -1 1 1 1 -1 -1 -1 - 1 1 1 1 1 1 1 1 1 -1 -1 -1 1 1 1 -1 -1 -1 -1 -1 -1 -1 -1 -1 - nonnegative - total_degree - HilbertSeries - -We could omit HilbertSeries, and the computation would include the Hilbert basis. The -type excluded_faces only affects the Hilbert series. In every other respect it is equivalent to -inequalities. -From the file CondorcetSemi.out we only display the Hilbert series: - Hilbert series: - 6 15 481 890 12346 ... 100915 69821 8655 4581 363 133 5 1 - denominator with 24 factors: - 1: 1 2: 14 4: 9 - - - shift = 1 - - - degree of Hilbert Series as rational function = -24 - -Surprisingly, this looks like the Hilbert series in the previous section read backwards, roughly -speaking. This is true, and one can explain it as we will see below. -It is justified to ask why we don’t use strict_inequalities instead of excluded_faces. -It does of course give the same Hilbert series. However, Normaliz cannot (yet) apply sym- -metrization in inhomogeneous computations. Moreover, the algorithmic approach is different, -and according to our experience excluded_faces is more efficient, independently of sym- -metrization. -See Section 7.20 for more information on excluded_faces. - - - - -2.10.2. At least one vote for every preference order - -Suppose we are only interested in elections in which every preference order is chosen by at -least one voter. This can be modeled as follows (Condorcet_one.in): - amb_space 24 - inequalities 3 - 1 1 1 1 1 1 -1 -1 -1 -1 -1 -1 1 1 -1 -1 1 -1 1 1 -1 -1 1 -1 - 1 1 1 1 1 1 1 1 -1 -1 1 -1 -1 -1 -1 -1 -1 -1 1 1 1 -1 -1 -1 - 1 1 1 1 1 1 1 1 1 -1 -1 -1 1 1 1 -1 -1 -1 -1 -1 -1 -1 -1 -1 - strict_signs - 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 - total_degree - HilbertSeries - -The entry 1 at position i of the vector strict_signs imposes the inequality xi ≥ 1. A −1 would -impose the inequality xi ≤ −1, and the entry 0 imposes no condition on the i-th coordinate. - Hilbert series: - 1 5 133 363 4581 8655 69821 100915 ... 12346 890 481 15 6 - denominator with 24 factors: - 1: 1 2: 14 4: 9 - - - shift = 24 - - - degree of Hilbert Series as rational function = -1 - - -Again we encounter (almost) the Hilbert series of the Condorcet paradox (without side con- -ditions). It is time to explain this coincidence. Let C be the Condorcet cone defined by the -nonstrict inequalities, M the monoid of lattice points in it, I1 ⊂ M the ideal of lattice points -avoiding the 3 facets defined by ties, I2 the ideal of lattice points with strictly positive coordi- -nates, and finally I3 the ideal of lattice points in the interior of C. Moreover, let 1 ∈ Z24 be the -vector with all entries 1. -Since 1 lies in the three facets defining the ties, it follows that I2 = M + 1. This explains why -we obtain the Hilbert series of I2 by multiplying the Hilbert series of M by t 24 , as just observed. -Generalized Ehrhart reciprocity (see [11, Theorem 6.70]) then explains the Hilbert series of I1 -that we observed in the previous section. Finally, the Hilbert series of I3 that we don’t have -displayed is obtained from that of M by “ordinary” Ehrhart reciprocity. But we can also obtain -I1 from I3 : I1 = I3 − 1, and generalized reciprocity follows from ordinary reciprocity in this -very special case. (Also see [16].) -The essential point in these arguments (apart from reciprocity) is that 1 lies in all support -hyperplanes of C except the coordinate hyperplanes. -You can easily compute the Hilbert series of I3 by making all inequalities strict. -As the terminal output shows, symmetrization has not been applied for the reason mentioned -above: strict_signs is an inhomogeneous input type. It would of course be possible to - - - -encode the strict signs as excluded_faces. Then the sparse format of matrices is very handy: - excluded_faces 24 - 1:1; - 1:2; - ... - 1:24; - -This is a shorthand for the unit matrix. - - -2.10.3. The f-vector with codimension bound - -Suppose we are interested in the f-vector of the cone defined by Condorcet.in. In view of the -rather high dimension the face lattice must be expected to be extremely large, but computing -the f-vector to codimension 4 should be no problem. (See [10] for the Normaliz face lattice -algorithm.) Indeed it is not. We use CondorcetFV.in: - ... - FVector - face_codim_bound 4 - -Then we find in the output file: - f-vector (possibly truncated): - 17550 2925 351 27 1 - -Note that the face numbers are listed by descending codimension or, equivalently, by increas- -ing dimension. The leftmost number is the number of faces in the highest codimension that -has been computed. So we have 17550 codimension 4 faces. - - -2.11. Testing normality -We want to test the monoid A4×4×3 defined by 4 × 4 × 3 contingency tables for normality -(see [12] for the background). The input file is A443.in: - amb_space 40 - cone_and_lattice 48 - 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 - ... - 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 1 - HilbertBasis - -Why cone_and_lattice? Well, we want to find out whether the monoid is normal, i.e., -whether M = C(M) ∩ gp(M). If M is even integrally closed in Z24 , then it is certainly inte- -grally closed in the evidently smaller lattice gp(M), but the converse does not hold in general, -and therefore we work with the lattice generated by the monoid generators. -It turns out that the monoid is indeed normal: - - - - original monoid is integrally closed in chosen lattice - -Actually the output file reveals that M is even integrally closed in Z24 : the external index is 1, -and therefore gp(M) is integrally closed in Z24 . -The output file also shows that there is a grading on Z24 under which all our generators have -degree 1. We could have seen this ourselves: Every generator has exactly one entry 1 in the -first 16 coordinates. (This is clear from the construction of M.) -A noteworthy detail from the output file: - size of partial triangulation = 48 - -It shows that Normaliz uses only a partial triangulation in Hilbert basis computations; see [12]. -It is no problem to compute the Hilbert series as well if you are interested in it. Simply add -q -to the command line or remove HilbertBasis from the input file. Then a full triangulation is -needed (size 2, 654, 272). -Similar examples are A543, A553 and A643. The latter is not normal, as we will see below. Even -on a standard PC or laptop, the Hilbert basis computation does not take very long because -Normaliz uses only a partial triangulation. The Hilbert series can still be determined, but the -computation time will grow considerably since the it requires a full triangulation. See [15] for -timings. - - -2.11.1. Computing just a witness - -If the Hilbert basis is large and there are many support hyperplanes, memory can become an -issue for Normaliz, as well as computation time. Often one is only interested in deciding -whether the given monoid is integrally closed (or normal). In the negative case it is enough -to find a single element that is not in the original monoid – a witness disproving integral -closedness. As soon as such a witness is found, Normaliz stops the Hilbert basis computation -(but will continue to compute other data if they are asked for). We look at the example A643.in -(for which the full Hilbert basis is not really a problem): - amb_space 54 - cone_and_lattice 72 - 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 ... - ... - 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 ... - WitnessNotIntegrallyClosed - - -Don’t add HilbertBasis because it will overrule IsIntegrallyClosed! -The output: - 72 extreme rays - 153858 support hyperplanes - - - - - embedding dimension = 54 - rank = 42 - external index = 1 - internal index = 1 - original monoid is not integrally closed in chosen lattice - witness for not being integrally closed: - 0 0 1 0 1 1 1 1 0 0 1 0 0 1 0 1 0 1 1 0 1 1 0 0 1 1 1 0 0 1 1 0 0 1 1 ... - - - grading: - 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 ... - - - degrees of extreme rays: - 1: 72 - - - *********************************************************************** - - 72 extreme rays: - 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 ... - ... - -If you repeat such a computation, you may very well get a different witness if several parallel -threads find witnesses. Only one of them is delivered. -If you just want to check integral closedness as quickly as possible, replace WitnessNotIntegrallyClosed -by IsIntegrallyClosed. Normaliz first checks some necessary conditions. If they are satis- -fied, the calculation of the Hilbert basis is started. If it finds a witness for not being integrally -closed, the witness is displayed in the output. - - -2.12. Convex hull computation/vertex enumeration -Normaliz computes convex hulls as should be very clear by now, and the only purpose of -this section is to emphasize that Normaliz can be restricted to this task by setting an explicit -computation goal. By convex hull computation we mean the determination of the support -hyperplanes of a polyhedron is given by generators (or vertices). The converse operation is -vertex enumeration. Both amount to the dualization of a cone, and can therefore be done by -the same algorithm. -As an example we take the input file cyclicpolytope30-15.in, the cyclic polytope of dimen- -sion 15 with 30 vertices (suggested by D. Avis and Ch. Jordan): - /* cyclic polytope of dimension 15 with 30 vertices */ - amb_space 16 - polytope 30 - 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 - 2 4 8 16 32 64 128 256 512 1024 2048 4096 8192 16384 32768 - ... - 30 900 27000 810000 ... 478296900000000000000 14348907000000000000000 - - - - - SupportHyperplanes - -Already the entries of the vertices show that the computation cannot be done in 64 bit arith- -metic. But you need not be worried. Just start Normaliz as usual. It will simply switch to -infinite precision by itself, as shown by the terminal output (use the option -c or --Verbose). - \.....| - Normaliz 3.2.0 \....| - \...| - (C) The Normaliz Team, University of Osnabrueck \..| - January 2017 \.| - \| - ************************************************************ - Compute: SupportHyperplanes - Could not convert 15181127029874798299. - Arithmetic Overflow detected, try a bigger integer type! - Restarting with a bigger type. - ************************************************************ - starting primal algorithm (only support hyperplanes) ... - Generators sorted lexicographically - Start simplex 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 - gen=17, 72 hyp - gen=18, 240 hyp - gen=19, 660 hyp - gen=20, 1584 hyp - gen=21, 3432 hyp - gen=22, 6864 hyp - gen=23, 12870 hyp - gen=24, 22880 hyp - gen=25, 38896 hyp - gen=26, 63648 hyp - gen=27, 100776 hyp - gen=28, 155040 hyp - gen=29, 232560 hyp - gen=30, 341088 hyp - Pointed since graded - Select extreme rays via comparison ... done. - ------------------------------------------------------------ - transforming data... done. - -Have a look at the output file if you are not afraid of 341088 linear forms. -If you have looked closely at the terminal output above, you should have stumbled on the lines - Could not convert 15181127029874798299. - Arithmetic Overflow detected, try a bigger integer type! - -They show that Normaliz has tried the computation in 64 bit integers, but encountered a num- - - - - -ber that is too large for this precision. It has automatically switched to infinite precision. (See -Section 5.3 for more information on integer types.) - - -2.13. Lattice points in a polytope and its Euclidean volume -The computation of lattice points in a polytope can be viewed as a truncated Hilbert basis -computation, and we have seen in preceding examples. But Normaliz can be restricted to -their computation, with homogeneous as well as with inhomogeneous input. Let us look at -ChF_8_1024.in: - - amb_space 8 - constraints 16 - 0.10976576 0.2153132834 ... 0.04282847494 >= -1/2 - ... - 0.10976576 -0.2153132834 ... -0.04282847494 >= -1/2 - 0.10976576 0.2153132834 ... 0.04282847494 <= 1/2 - 0.10976576 -0.2153132834 ...-0.04282847494 <= 1/2 - LatticePoints - ProjectionFloat - - -This example comes from numerical analysis; see Ch. Kacwin, J. Oettershagen and T. Ullrich, -On the orthogonality of the Chebyshev-Frolov lattice and applications, Monatsh. Math. 184 -(2017), 425–441). Its origin explains the decimal fractions in the input. Normaliz converts -them immediately into ordinary fractions of type numerator/denominator, and then makes the -input integral as usual. -In the output file you can see to what integer vectors Normaliz has converted the inequalities -of the input file: - 16 support hyperplanes of polyhedron (homogenized): - 5488288000 10765664170 ... 2141423747 25000000000 - ... - -5488288000 10765664170 ... 2141423747 25000000000 - -The option ProjectionFloat indicates that we want to compute the lattice points in the poly- -tope defined by the inequalities and that we want to use the floating point variant of the -project-and-lift algorithm; Projection would make Normaliz use its ordinary arithmetic in -this algorithm. For our example the difference in time is not really significant, but when you -try VdM_16_1048576.in, it becomes very noticeable. Let us have a look at the relevant part of -then terminal output: - Polyhedron is parallelotope - Computing lattice points by project-and-lift - LLL based on support hyperplanes - Projection - embdim 9 inequalities 16 - ... - - - - - embdim 6 inequalities 140 - ... - embdim 2 inequalities 2 - embdim 1 inequalities 0 - Lifting - Lifting to dimension 2 - Lifting to dimension 3 - ... - Lifting to dimension 8 - Lifting to dimension 9 - embdim 2 LatticePoints 5 - embdim 3 LatticePoints 21 - ... - embdim 8 LatticePoints 907 - embdim 9 LatticePoints 1067 - Project-and-lift complete - -We start with embedding dimension 9 since we need a homogenizing coordinate in inhomoge- -neous computations. Then the polytope is successively projected onto a coordinate hyperplane -until we reach a line segment given by 2 inequalities. In the second part Normaliz lifts the lat- -tice points back through all projections. The following figure illustrates the procedure for a -polygon that is projected to a line segment. - - - - -The green lines show the fibers over the lattice points in the (red) line segment. Note that -not every lattice point in the projection must be liftable to a lattice point in the next higher -dimension. -In ChF_8_1024.out we see - 1067 lattice points in polytope (module generators): - -4 0 0 0 0 0 0 0 1 - -3 0 0 0 -1 0 0 0 1 - -3 0 0 0 0 0 0 0 1 - ... - 3 0 0 0 0 0 0 0 1 - 3 0 0 0 1 0 0 0 1 - 4 0 0 0 0 0 0 0 1 - -Normaliz finds out that our polytope is in fact a parallelotope. This allows Normaliz to sup- -press the computation of its vertices. We are not interested in them, and they look frightening - - - -when written as ordinary fractions (computed with the additional option SupportHyperplanes). -This is only the first vertex, the denominator is the number in the last row: - 256 vertices of polyhedron: - -7831972155307708173239167258085974255845869779051329651906336771582421875 - -2560494334732147696394408175864650673712115229853232268085759500000000000 - 2411932924117448250036041241683237083742860005142447171295674845000000000 - -2170682283899852950367663781367299946065844697990214478942400250000000000 - 1846013540077621750562232333569651551559659207659438074760922800500000000 - -1450403531662801634587765586956338287943865886737024582718631750000000000 - 999055328718773316303519268629091038893656784654239444024061220000000000 - -509313990522468215816366827427428831508901797188810249435062450000000000 - 2292486335803169657316823615602461625422283571089603408672092012129842506 - ... - -Not all polytopes are parallelotopes, and in most cases Normaliz must compute the vertices or -extreme rays as an auxiliary step, even if we are not interested in them. You can always add -the option -NoExtRaysOutput -if you want to suppress their output. (The numerical information on the number of extreme -rays etc. will however be included in the output file if it is available.) Similarly one can -suppress the output of support hyperplanes by -NoSuppHypsOutput -On the other hand, the information provided by the vertices or support hyperplanes may be -important. Instead of the unreadable integer output shown above, you can ask for -VerticesFloat -Then the vertices of polyhedra are printed in floating point format: - 256 vertices of polyhedron: - -3.41637 -1.11691 1.0521 ... 0.435796 -0.222167 1 - -3.41637 -0.946868 0.435796 ... -1.0521 0.632677 1 - ... - -Note that they can only be printed if a polyhedron is defined. This is always the case in -inhomogeneous computations, but in the homogeneous case a grading is necessary. There is -also a variant ExtremeRaysFloat. -Similarly we can get the support hyperplanes in floating point format (they are only defined -up to a positive scalar multiple) by -SuppHypsFloat -resulting in - 16 support hyperplanes of polyhedron (homogenized): - -0.219532 -0.430627 -0.405641 ... -0.168022 -0.0856569 1 - -0.219532 -0.365068 -0.168022 ... 0.405641 0.24393 1 - - - - - ... - -By its construction, our polytope should have Euclidean volume 1024. We can confirm this -number by computing the volume, using the option -Volume, -V -We get - volume (normalized) = 205078125000...00/49670537275735342575...58763 - volume (normalized, float) =41287680.0308 - volume (Euclidean) = 1024.00000076 - -The result makes us happy, despite of the small inaccuracy of the floating point computation -on which the Euclidean volume is based. See Section 7.1.1 for a discussion of volumes and -multiplicities. - - -2.14. The integer hull -The integer hull of a polyhedron P is the convex hull of the set of lattice points in P (despite of -its name, it usually does not contain P). Normaliz computes by first finding the lattice points -and then computing the convex hull. The computation of the integer hull is requested by the -computation goal IntegerHull. -The computation is somewhat special since it creates a second cone (and lattice) Cint . In -homogeneous computations the degree 1 vectors generate Cint by an input matrix of type -cone_and_lattice. In inhomogeneous computations the module generators and the Hilbert -basis of the recession cone are combined and generate Cint . Therefore the recession cone is -reproduced, even if the polyhedron should not contain a lattice point. -The integer hull computation itself is always inhomogeneous. The output file for Cint is -.IntHull.out. -As a very simple example we take rationalIH.in (rational.in augmented by IntegerHull): - amb_space 3 - cone 3 - 1 1 2 - -1 -1 3 - 1 -2 4 - grading - unit_vector 3 - HilbertSeries - IntegerHull - -It is our rational polytope from Section 2.5. We know already that the origin is the only lattice -point it contains. Nevertheless let us have a look at rationalIH.IntHull.out: - 1 vertices of polyhedron - 0 extreme rays of recession cone - - - - - 1 support hyperplanes of polyhedron (homogenized) - - - embedding dimension = 3 - affine dimension of the polyhedron = 0 - rank of recession monoid = 0 (polyhedron is polytope) - internal index = 1 - - - - *********************************************************************** - - 1 vertices of polyhedron: - 0 0 1 - - - 0 extreme rays of recession cone: - - - 1 support hyperplanes of polyhedron (homogenized): - 0 0 1 - - - 2 equations: - 1 0 0 - 0 1 0 - - - 1 basis elements of generated lattice: - 0 0 1 - - -Since the lattice points in P are already known, the goal was to compute the constraints defin- -ing the integer hull. Note that all the constraints defining the integer hull can be different from -those defining P. In this case the integer hull is cit out by the 2 equations. -As a second example we take the polyhedron of Section 2.9. The integer hull is the “green” -polyhedron: - - - - -The input is InhomIneqIH.in (InhomIneq.in augmented by IntegerHull). The data of the -integer hull are found in InhomIneqIH.IntHull.out: - ... - 2 vertices of polyhedron: - -1 0 1 - 0 1 1 - - - - - 1 extreme rays of recession cone: - 1 0 0 - - - 3 support hyperplanes of polyhedron (homogenized): - 0 -1 1 - 0 1 0 - 1 -1 1 - - - - -2.15. Inhomogeneous congruences -We want to compute the nonnegative solutions of the simultaneous inhomogeneous congru- -ences - - x1 + 2x2 ≡ 3 (7), - 2x1 + 2x2 ≡ 4 (13) - -in two variables. The input file InhomCong.in is - amb_space 2 - constraints 2 symbolic - x[1] + 2x[2] ~ 3 (7); - 2x[1] + 2x[2] ~ 4 (13); - -This is an example of input of symbolic constraints. We use ~ as the best ASCII character for -representing the congruence sign ≡. -Alternatively one can use a matrix in the input As for which we must move the right hand side -over to the left. - amb_space 2 - inhom_congruences 2 - 1 2 -3 7 - 2 2 -4 13 - -It is certainly harder to read. -The first vector list in the output: - 3 module generators: - 0 54 1 - 1 1 1 - 80 0 1 - - -Easy to check: if (1, 1) is a solution, then it must generate the module of solutions together -with the generators of the intersections with the coordinate axes. Perhaps more difficult to -find: - 6 Hilbert basis elements of recession monoid: - 0 91 0 - - - - - 1 38 0 - 3 23 0 1 vertices of polyhedron: - 5 8 0 0 0 91 - 12 1 0 - 91 0 0 - -Strange, why is (0, 0, 1), representing the origin in R2 , not listed as a vertex as well? Well the -vertex shown represents an extreme ray in the lattice E, and (0, 0, 1) does not belong to E. - 2 extreme rays of recession cone: - 0 91 0 - 91 0 0 - - - 3 support hyperplanes of polyhedron (homogenized) - 0 0 1 - 0 1 0 - 1 0 0 - - - 1 congruences: - 58 32 1 91 - - -Normaliz has simplified the system of congruences to a single one. - 3 basis elements of generated lattice: - 1 0 33 - 0 1 -32 - 0 0 91 - -Again, don’t forget that Normaliz prints a basis of the efficient lattice E. - - -2.15.1. Lattice and offset - -The set of solutions to the inhomogeneous system is an affine lattice in R2 . The lattice basis -of E above does not immediately let us write down the set of solutions in the form w + L0 with -a subgroup L0 , but we can easily transform the basis of E: (1, 1, 1) is in E and we use it to -reduce the third column of the other two basis elements to 0. Try the file InhomCongLat.in: - amb_space 2 - offset - 1 1 - lattice 2 - 5 8 - -12 -1 - - - - -2.15.2. Variation of the signs - -Suppose we want to solve the system of congruences under the condition that both variables -are negative (InhomCongSigns.in): - amb_space 2 - inhom_congruences 2 - 1 2 -3 7 - 2 2 -4 13 - signs - -1 -1 - - -The two entries of the sign vector impose the sign conditions x1 ≤ 0 and x2 ≤ 0. -From the output we see that the module generators are more complicated now: - 4 module generators: - -11 0 1 - -4 -7 1 - -2 -22 1 - 0 -37 1 - -The Hilbert basis of the recession monoid is simply that of the nonnegative case multiplied by -−1. - - -2.16. Integral closure and Rees algebra of a monomial ideal -Next, let us discuss the example MonIdeal.in (typeset in two columns): - amb_space 5 - rees_algebra 9 - 1 2 1 2 1 0 3 4 - 3 1 1 3 5 1 0 1 - 2 5 1 0 2 4 1 5 - 0 2 4 3 2 2 2 4 - 0 2 3 4 - - -The input vectors are the exponent vectors of a monomial ideal I in the ring K[X1 , X2 , X3 , X4 ]. -We want to compute the normalization of the Rees algebra of the ideal. In particular we can -extract from it the integral closure of the ideal. Since we must introduce an extra variable T , -we have amb_space 5. -In the Hilbert basis we see the exponent vectors of the Xi , namely the unit vectors with last -component 0. The vectors with last component 1 represent the integral closure I of the ideal. -There is a vector with last component 2, showing that the integral closure of I 2 is larger than I . - 16 Hilbert basis elements: - 0 0 0 1 0 - - - - - ... - 5 1 0 1 1 - 6 5 2 2 2 - - - 11 generators of integral closure of the ideal: - 0 2 3 4 - ... - 5 1 0 1 - -The output of the generators of I is the only place where we suppress the homogenizing vari- -able for “historic” reasons. If we extract the vectors with last component 1 from the extreme -rays, then we obtain the smallest monomial ideal that has the same integral closure as I. - 10 extreme rays: - 0 0 0 1 0 - ... - 5 1 0 1 1 - -The support hyperplanes which are not just sign conditions describe primary decompositions -of all the ideals I k by valuation ideals. It is not hard to see that none of them can be omitted for -large k (for example, see: W. Bruns and G. Restuccia, Canonical modules of Rees algebras. J. -Pure Appl. Algebra 201, 189–203 (2005)). - 23 support hyperplanes: - 0 0 0 0 1 - 0 ... - 6 0 1 3 -13 - - - -2.16.1. Only the integral closure of the ideal - -If only the integral closure of the ideal is to be computed, one can choose the input as follows -(IntClMonId.in): - amb_space 4 - vertices 9 - 1 2 1 2 1 - ... - 2 2 2 4 1 - cone 4 - 1 0 0 0 - 0 1 0 0 - 0 0 1 0 - 0 0 0 1 - -The generators of the integral closure appear as module generators in the output and the gen- -erators of the smallest monomial ideal with this integral closure are the vertices of the polyhe- -dron. - - - -4. The input file -The input file .in consists of items. There are several types of them: - (1) definition of the ambient space, - (2) matrices with integer or rational entries (depending on the type), - (3) vectors with integer entries, - (4) constraints in tabular or symbolic format, - (5) a polynomial, - (6) computation goals and algorithmic variants, - (7) numerical parameters, - (8) number field definition, - (9) input types for fusion rings, -(10) comments. -An item cannot include another item. In particular, comments can only be inserted between -other items, but not within another item. Matrices and vectors can have two different formats, -plain and formatted. -Matrices and vectors are classified by the following attributes: - (1) generators, constraints, accessory, - (2) cone/polyhedron, (affine) lattice, - (3) homogeneous, inhomogeneous. -The line structure is irrelevant for the interpretation of the input, but it is advisable to use it for -the readability of the input file. -The input syntax of Normaliz 2 can still be used. It is explained in Appendix C. - - -4.1. Input items -4.1.1. The ambient space and lattice - -The ambient space is specified as follows: - amb_space - -where stands for the dimension d of the ambient vector space Rd in which the geometric -objects live. The ambient lattice A is set to Zd . -Alternatively one can define the ambient space implicitly by - amb_space auto - -In this case the dimension of the ambient space is determined by Normaliz from the first -formatted vector or matrix in the input file. It is clear that any input item that requires the -knowledge of the dimension can only follow the first formatted vector or matrix. -In the following the letter d will always denote the dimension set with amb_space. - - - -An example: - amb_space 5 - -indicates that polyhedra and lattices are subobjects of R5 . The ambient lattice is Z5 . -The first non-comment input item must specify the ambient space. - - -4.1.2. Plain vectors - -A plain vector is built as follows: - - - - denotes the type and is the vector itself. The number of components is determined -by the type of the vector and the dimension of the ambient space. At present, all vectors have -length d. -Example: - grading - 1 0 0 - -Normaliz allows also the input of sparse vectors. Sparse input is signalized by the key word -sparse as the first entry. It is followed by entries of type : where denotes -the column and the value in that column. (The unspecified columns have entry 0.) A -sparse vector is terminated by the character ; . Example: - grading - sparse 1:1; - -One can also set a range of entries in sparse vectors like in - grading - sparse 1:1 3..5:-1 7:1; - -which produces the vector (1, 0, −1, −1, −1, 0, 1, 0 . . . , 0). -For unit vectors vectors there exists a shortcuts. Example: - total_degree - unit_vector 25 - - - -4.1.3. Formatted vectors - -A formatted vector is built as follows: - - [ ] - - - - -where denotes the type and is the vector itself. The components can be separated -by white space, commas or semicolons. An example showing all possibilities (not recom- -mended): - grading - [1,0; 0 5] - - - -4.1.4. Plain matrices - -A plain matrix is built as follows: - - - ... - - -Here denotes the type of the matrix, the number of rows, and ,. . . , are -the rows. Some types allow rational and floating point matrix entries, others are restricted to -integers; see Sections 4.1.9 and 4.1.10. -The number of columns is implicitly defined by the dimension of the ambient space and the -type of the matrix. Example (with amb_space 3): - cone 3 - 1/3 2 3 - 4 5 6 - 11 12/7 13/21 - -Normaliz allows the input of matrices in transposed form: - transpose - - ... - - -Note that is now the number of columns of the matrix that follows it (assumed to be the -number of input vectors). The number of rows is determined by the dimension of the ambient -space and the type of the matrix. Example: - cone transpose 3 - 1 0 3/2 - 0 1/9 4 - -is equivalent to - cone 3 - 1 0 - 0 1/9 - 3/2 4 - - - - -Like vectors, matrices have a sparse input variant, again signalized by the key word sparse. -The rows are sparse vectors with entries :, and each row is concluded by the -character ;. Also here one can set a range of coordinates to the same value: -Example: - inequalities 2 sparse - 1:1 2:-1; - 3-5:-1; - -chooses the 3 × 3 unit matrix as a matrix of type inequalities. Note that also in case of -transposed matrices, sparse entry is row by row. -Matrices may have zero rows. Such empty matrices like - inhom_inequalities 0 - -can be used to make the input inhomogeneous (Section 4.1.17) or to avoid the automatic choice -of the positive orthant in certain cases (Section 4.1.18). (The empty inhom_inequalities have -both effects simultaneously.) Apart from these effects, empty matrices have no influence on -the computation. - - -4.1.5. Formatted matrices - -A formatted matrix is built as follows: - - [ [] - ... - [] ] - -Here denotes the type of the matrix and ,. . . , are vectors. Legal separators -are white space, commas and semicolons. An example showing all possibilities (not really -recommended): - cone [ - [ 2 1][3/7 4]; - [0 1], - [9 10] [11 12/13] - ] - -Similarly as plain matrices, formatted matrices can be given in transposed form, and they can -be empty. - - -4.1.6. Constraints in tabular format - -This input type is somewhat closer to standard notation than the encoding of constraints in -matrices. The general type of equations and inequalities is - - - - - ; - -where denotes a vector of length d, is one of the relations =, <=, >=, <, > and -is a number. -Congruences have the form - ~ (); - -where is a nonzero integer. -Examples: - 1/2 -2 >= 0.5 - 1 -1/7 = 0 - -1 1 ~ 7 (9) - -Note: all numbers and relation signs must be separated by white space. - - -4.1.7. Constraints in symbolic format - -This input type is even closer to standard notation than the encoding of constraints in matrices -or in tabular format. It is especially useful if the constraints are sparse. Instead of assigning a -value to a coordinate via its position in a vector, it uses coordinates named x[] where -is the index of the coordinate. The index is counted from 1. -The general type of equations and inequalities is - ; - -where and denote affine linear function of the x with rational coefficients. As -above, is one of the relations =, <=, >=, <, >. (Both and must be nonempty.) -Note the terminating semicolon. -Congruences have the form - ~ (); - -where is a nonzero integer and and are affine linear functions with integer -coefficients. -Examples: - 1/3x[1] >= 2x[2] + 5; - x[1]+1=1/4x[2] ; - -x[1] + x[2] ~ 7 (9); - -There is no need to insert white space for separation, but it may be inserted anywhere where -it does not disrupt numbers or relation signs. - - - - -4.1.8. Polynomials - -For the computation of weighted Ehrhart series and integrals Normaliz needs the input of -a polynomial with rational coefficients. Moreover, one can apply polynomial constraints to -lattice points in polytopes. A polynomial is first read as a string. For the computation the -string is converted by the input function of CoCoALib [2]. Therefore any string representing -a valid CoCoA expression is allowed. However, the names of the indeterminates are fixed: -x[1],. . . ,x[ where ] is the value of amb_space. The polynomial must be concluded by -a semicolon. -Example: - (x[1]+1)*(x[1]+2)*(x[1]+3)*(x[1]+4)*(x[1]+5)* - (x[2]+1)*(x[3]+1)*(x[4]+1)*(x[5]+1)*(x[6]+1)*(x[7]+1)* - (x[8]+1)*(x[8]+2)*(x[8]+3)*(x[8]+4)*(x[8]+5)*1/14400; - - - (x[1]*x[2]*x[3]*x[4])^2*(x[1]-x[2])^2*(x[1]-x[3])^2* - (x[1]-x[4])^2*(x[2]-x[3])^2*(x[2]-x[4])^2*(x[3]-x[4])^2; - - - -4.1.9. Rational numbers - -Rational numbers are allowed in input matrices, but not in all. They are not allowed in vectors -and in matrices containing lattice generators and in congruences, namely in - lattice cone_and_lattice offset open_facets - congruences inhom_congruences rees_algebra lattice_ideal - grading dehomogenization signs strict_signs - -They are allowed in saturation since it defines the intersection of the vector space generated -by the rows of the matrix with the integral lattice. -Avoid negative numbers as denominators. -Normaliz first reduces the input numbers to lowest terms. Then each row of a matrix is mul- -tiplied by the least common multiple of the denominators of its entries. In all applications -in which the original monoid generators play a role, one should use only integers in input -matrices to avoid any ambiguity. - - -4.1.10. Decimal fractions and floating point numbers - -Normaliz accepts decimal fractions and floating point numbers in its input files. These are -precisely converted to ordinary fractions (or integers). Examples: - 1.1 --> 11/10 0.5 --> 1/2 -.1e1 --> -1 - -It is not allowed to combine an ordinary fraction and a decimal fraction in the same number. -In other words, expressions like 1.0/2 are not allowed. - - - - -4.1.11. Numbers in algebraic extensions of Q - -Their format is explained in Section 8.1 together with the definition of number fields. - -4.1.12. Numerical parameters - -Their input has the form - - -where is the value assigned to . - -4.1.13. Computation goals and algorithmic variants - -These are single or compound words, such as - HilbertBasis - Multiplicity - -The file can contain several computation goals, as in this example. - -4.1.14. Input types for fusion rings - -See Appendix H. - -4.1.15. Comments - -A comment has the form - /* */ - -where stands for the text of the comment. It can have arbitrary length and stretch over -several lines. Example: - /* This is a comment - */ - -Comments are only allowed at places where also a new keyword would be allowed, especially -not between the entries of a matrix or a vector. Comments can not be nested. - -4.1.16. Restrictions - -Input items can be combined quite freely, but there are some restrictions: - (1) The types - cone, cone_and_lattice, polytope, rees_algebra - exclude each other mutually. - - - - (2) The input type subspace excludes polytope and rees_algebra. - (3) The types - lattice, saturation, cone_and_lattice - exclude each other mutually. - (4) polytope can not be combined with grading. - (5) The only type that can be combined with lattice_ideal is grading. - (6) The following types cannot be combined with inhomogeneous types or dehomogenization: - polytope, rees_algebra, excluded_faces - (7) The following types cannot be combined with inhomogeneous types: - dehomogenization - (8) Special restrictions apply for the input type open_facets; see Section 4.15. - (9) Special rules apply if precomputed data are used. See Section 7.23. -(10) For restrictions that apply to algebraic polyhedra see Section 8. Similar restrictions - apply if the input types rational_lattice and rational_offset are used (see Sec- - tion 7.21). -(11) The input types monoid, toric_ideal, normal_toric_ideal and lattice_ideal al- - loow only grading as a further input type. -A non-restriction: the same type can appear several times. This is useful if one wants to -combine different formats, for example - inequalities 2 sparse - 1:1; - 1:1 3:-1; - inequalities 2 - 1 1 0 1 - 1 -1 -1 0 - - - -4.1.17. Homogeneous and inhomogeneous input - -Apart from the restrictions listed in the previous section, homogeneous and inhomogeneous -types can be combined as well as generators and constraints. A single inhomogeneous type -or dehomogenization in the input triggers an inhomogeneous computation. The input item of -inhomogeneous type may be an empty matrix. - - -4.1.18. Default values - -If there is no lattice defining item, Normaliz (virtually) inserts the the unit matrix as an input -item of type lattice. If there is no cone defining item, the unit matrix is (additionally) inserted -as an input item of type cone. -If the input is inhomogeneous, then Normaliz provides default values for vertices and the -offset as follows: - (1) If there is an input matrix type lattice, but no offset, then the offset 0 is inserted. - - - - (2) If there is an input matrix of type cone, but no vertices, then the vertex 0 is inserted. -An important point. If the input does not contain any cone generators or inequalities, Nor- -maliz automatically assumes that you want to compute in the positive orthant. In order to -avoid this you can use the directive -no_pos_orth_def -Equivalently you can add an empty matrix of inequalities, inhom_inequalities or strict_inequalities. -This will not affect the results. - - -4.1.19. Normaliz takes intersections - -The input may contain several cone defining items and several lattice defining items. We con- -sider homogeneous input for simplicity. Inhomogeneous input is made homogeneous anyway. -One can subdivide the input items defining cones and lattices as follows: - 1. cone generators: together they generate a cone C1 ; - 2. cone constraints, namely inequalities and equations: they define the cone C2 ; - 3. lattice generators: they generate the sublattice L1 and the vector subspace U1 = RL1; - 4. lattice constraints, namely equations and congruences: they define the sublattice L2 and - the vector subspace U2 = RL2 . -The cone defined by all these data is C=C1 ∩ C2 ∩ U1 ∩ U2 . The lattice defined by them is -RC ∩ L1 ∩ L2 . - - -4.2. Homogeneous generators -4.2.1. Cones - -The main type is cone. The other two types are added for special computations. -cone is a matrix with d columns. Every row represents a vector, and they define the cone - generated by them. Section 2.3, 2cone.in -subspace is a matrix with d columns. The linear subspace generated by the rows is added to - the cone. Section 7.13.4. -polytope is a matrix with d − 1 columns. It is internally converted to cone extending each - row by an entry 1. Section 2.4, polytope.in. This input type automatically sets - NoGradingDenom and defines the grading (0, . . . , 0, 1). Not allowed in combination with - inhomogeneous types. -rees_algebra is a matrix with d − 1 columns. It is internally converted to type cone in two - steps: (i) each row is extended by an entry 1 to length d. (ii) The first d − 1 unit vectors - of length d are appended. Section 2.16, MonIdeal.in. Not allowed in combination with - inhomogeneous types. -extreme_rays is a matrix with d columns. See Section 7.23 for its use. -maximal_subspace is a matrix with d columns. See Section 7.23 for its use. - - - - -Moreover, it is possible to define a cone and a lattice by the same matrix: -cone_and_lattice The vectors of the matrix with d columns define both a cone and a lattice. - Section 2.11, A443.in. - If subspace is used in combination with cone_and_lattice, then the sublattice gener- - ated by its rows is added to the lattice generated by cone_and_lattice. -The Normaliz 2 types integral_closure and normalization can still be used. They are -synonyms for cone and cone_and_lattice, respectively. - - -4.2.2. Lattices - -There are 5 types. With the exception of rational_lattice and saturation their entries are -integers. -lattice is a matrix with d columns. Every row represents a vector, and they define the lattice - generated by them. Section 2.6.3, 3x3magiceven_lat.in. -rational_lattice is a matrix with d columns. Its entries can be fractions. Every row repre- - sents a vector, and they define the sublattice of Qd generated by them. See Section 7.21, - ratlat_2.in. -saturation is a matrix with d columns. Every row represents a vector, and they define the lat- - tice U ∩Zd where U is the subspace generated by them. Section 2.6.3, 3x3magic_sat.in. - (If the vectors are integral, then U ∩Zd is the saturation of the lattice generated by them.) -cone_and_lattice See Section 4.2.1. -generated_lattice is a matrix with d columns. See Section 7.23 for its use. -hilbert_basis_rec_cone is a matrix with d columns. It contains the precomputed Hilbert - basis of the recession cone. See Section 7.23.3. - - -4.2.3. Affine monoids - -monoid is a matrix with d columns. Every row represents a vector, and they generate a sub- - monoid of Z. See Section 3, monoid.in, A443monoid.in. - - -4.3. Homogeneous Constraints -The coefficients ξi of the constraints are rational numbers unless indicated otherwise. - - -4.3.1. Cones - -inequalities is a matrix with d columns. Every row (ξ1 , . . . , ξd ) represents a homogeneous - inequality - ξ1 x1 + · · · + ξd xd ≥ 0 - for the vectors (x1 , . . . , xd ) ∈ Rd . Sections 2.3.2, 2.5.2, 2cone_ineq.in, poly_ineq.in - - - - -equations is a matrix with d columns. Every row (ξ1 , . . . , ξd ) represents an equation - - ξ1 x1 + · · · + ξd xd = 0 - for the vectors (x1 , . . . , xd ) ∈ Rd . Section 2.6, 3x3magic.in -signs is a vector with d entries in {−1, 0, 1}. It stands for a matrix of type inequalities - composed of the sign inequalities xi ≥ 0 for the entry 1 at the i-th component and the - inequality xi ≤ 0 for the entry −1. The entry 0 does not impose an inequality. See - Section 2.15.2, InhomCongSigns.in. -excluded_faces is a matrix with d columns. Every row (ξ1 , . . . , ξd ) represents an inequality - - ξ1 x1 + · · · + ξd xd > 0 - for the vectors (x1 , . . . , xd ) ∈ Rd . It is considered as a homogeneous input type though - it defines inhomogeneous inequalities. The faces of the cone excluded by the inequali- - ties are excluded from the Hilbert series computation, but excluded_faces behave like - inequalities in almost every other respect. Section 2.10.1, CondorcetSemi.in. Also - see Section 7.20. -support_hyperplanes is a matrix with d columns. See Section 7.23. -A useful shortcut: -nonnegative inserts the sign inequalities xi ≥ 0 for all coordinates. See Condorcet.in. - - -4.3.2. Lattices - -congruences is a matrix with d +1 columns. Each row (ξ1 , . . . , ξd , c) represents a congruence - - ξ1 z1 + · · · + ξd zd ≡ 0 mod c, ξi , c ∈ Z, - for the elements (z1 , . . . , zd ) ∈ Zd . Section 2.6.2, 3x3magiceven.in. - - -4.4. Inhomogeneous generators -4.4.1. Polyhedra - -vertices is a matrix with d +1 columns. Each row (p1 , . . . , pd , q), q > 0, specifies a generator - of a polyhedron (not necessarily a vertex), namely -   - p1 pn - vi = ,..., , pi ∈ Q, q ∈ Q>0 , - q q - Section 2.9.1, InhomIneq_gen.in - Note: vertices and cone together define a polyhedron. If vertices is present in the - input, then the default choice for cone is the empty matrix. -The format of vertices was introduced when Normaliz only accepted integer numbers in its -input. There is no need for an extra denominator anymore, but for backward compatibility the -format has not been changed. -The Normaliz 2 input type polyhedron can still be used. - - - -4.4.2. Affine lattices - -offset is a vector with d integer entries. It defines the origin of the affine lattice. Sec- - tion 2.15.1, InhomCongLat.in. -rational_offset is a vector with d rational entries. It defines the origin of the rational affine - lattice. Section 7.21, ratlat_2.in. -Note: offset and lattice (or saturation) together define an affine lattice. If offset is -present in the input, then the default choice for lattice is the empty matrix. - - -4.5. Inhomogeneous constraints -4.5.1. Polyhedra - -inhom_inequalities is a matrix with d + 1 columns. We consider inequalities - - ξ1 x1 + · · · + ξd xd ≥ η, - - rewritten as - ξ1 x1 + · · · + ξd xd + (−η) ≥ 0 - and then represented by the input vectors - - (ξ1 , . . . , ξd , −η). - - Section 2.9, InhomIneq.in. -inhom_equations is a matrix with d + 1 columns. We consider equations - - ξ1 x1 + · · · + ξd xd = η, - - rewritten as - ξ1 x1 + · · · + ξd xd + (−η) = 0 - and then represented by the input vectors - - (ξ1 , . . . , ξd , −η). - - See Section 2.7NumSemi.in. -strict_inequalities is a matrix with d columns. We consider inequalities - - ξ1 x1 + · · · + ξd xd ≥ 1, - - represented by the input vectors - (ξ1 , . . . , ξd ). - Section 2.3.3, 2cone_int.in. -strict_signs is a vector with d components in {−1, 0, 1}. It is the “strict” counterpart to - signs. An entry 1 in component i represents the inequality xi > 0, an entry −1 the oppo- - site inequality, whereas 0 imposes no condition on xi . Section 2.10.2, Condorcet_one.in - - - -inhom_excluded_faces is a matrix with d + 1 columns. Every row (ξ1 , . . . , ξd , −η) repre- - sents an inequality - ξ1 x1 + · · · + ξd xd > η - for the vectors (x1 , . . . , xd ) ∈ Rd . The faces of the polyhedron excluded by the in- - equalities are excluded from the Hilbert and Ehrhart series series computation, but - inhom_excluded_faces behave like inhom_inequalities in almost every other re- - spect. See Section 7.20. - - -4.5.2. Affine lattices - -inhom_congruences We consider a matrix with d + 2 columns. Each row (ξ1 , . . . , ξd , −η, c) - represents a congruence - - ξ1 z1 + · · · + ξd zd ≡ η mod c, ξi , η, c ∈ Z, - - for the elements (z1 , . . . , zd ) ∈ Zd . Section 2.15, InhomCongSigns.in. - - -4.6. Tabular constraints -constraints allows the input of equations, inequalities and congruences in a for- - mat that is close to standard notation. As for matrix types the keyword constraints - is followed by the number of constraints. The syntax of tabular constraints has been - described in Section 4.2.1. If (ξ1 , . . . , ξd ) is the vector on the left hand side and η the - number on the right hand side, then the constraint defines the set of vectors (x1 , . . . , xd ) - such that the relation - ξ1 x1 + · · · + ξd xd rel η - is satisfied, where rel can take the values =, ≤, ≥, <, > with the represented by input - strings =,<=,>=,<,>, respectively. - Tabular constraints cannot be used for excluded_faces or inhom_excluded_faces. - A further choice for rel is ~. It represents a congruence ≡ and requires the additional - input of a modulus: the right hand side becomes η(c). It represents the congruence - - ξ1 x1 + . . . ξd xd ≡ η (mod c). - - Sections 2.3.3, 2cone_int.in, 2.6.2, 3x3magiceven.in, 2.9, InhomIneq.in. -A right hand side ̸= 0 makes the input inhomogeneous, as well as the relations < and >. Strict -inequalities are always understood as conditions for integers. So - - ξ1 x1 + · · · + ξd xd < η - -is interpreted as - ξ1 x1 + . . . ξd xd ≤ η − 1, - - - - -4.6.1. Forced homogeneity - -It is often more natural to write constraints in inhomogeneous form, even when one wants the -computation to be homogeneous. The type constraints does not allow this. Therefore we -have introduced -hom_constraints for the input of equations, non-strict inequalities and congruences in the - same format as constraints, except that these constraints are meant to be for a homo- - geneous computation. It is clear that the left hand side has only d − 1 entries now. See - Section 2.5.2, poly_hom_const.in. - - -4.7. Symbolic constraints -The input syntax is -constraints symbolic where is the number of constraints in symbolic form that - follow. -The constraints have the form described in Section 4.1.7. Note that every symbolic constraint -(including the last) must be terminated by a semicolon. -See Sections 2.7, NumSemi.in, 2.15, InhomCong.in. -The interpretation of homogeneity follows the same rules as for tabular constraints. The vari- -ant hom_constraints is allowed and works as for tabular constraints. - - -4.8. Blocking the coordinate transformation -For certain tasks Normaliz must perform a coordinate transformation. Without an option -blocking it, it is performed if at least one of the following is contained in the input: - (1) generators, - (3) equations, - (2) congruemces. -It is difficult for Normaliz to predict whether the coordinate transformation is really necessary. -The main task for which it is superfluous is the computation of lattice points by project-and- -lift, provided there are only equations, inequalities and congruences in the input. In case (1) -the coordinate transformation cannot be blocked, and an attempt to do it will result in an -BadInputException. -You can always ask for -convert_equations -namely into inequalities. This is a harmless step, and it will often block the coordinate trans- -formation in the input phase. This does not completely avoid the coordinate transformation in -case (3). Then the directive -no_coord_transf - - - - -can be used. It implies convert_equations. -The coordinate transformation tries to simplify the coordinate system by LLL reduction, at -least in low dimensions. This can be an arithmetically dangerous step. Adding NoLLL to your -cone properties may be useful then. - - -4.9. Polynomial constraints -Normaliz can apply polynomial constraints to lattice points in polytopes. The input syntax is -polynomial_equations -polynomial_inequalities -where is the number of polynomials that follow. The equations defined by a polynomial -f is always given by f (x) = 0, and the inequality is f (x) ≥ 0. Therefore no relation signs or -“right hand sides” are allowed.Don’t forget to conclude every polynomial by a semicolon. -See pet.in, baby.in and Section 7.2.5. - - -4.10. Binomial ideals -There are three types of input for binomial ideals. The rows of the matrices coming with these -input types represent binomials. The representation of binomials by vectors is discussed in -Section 3.1.2. -The input types differ in the object computed from them. -lattice_ideal is an integer matrix with d columns. The object computed from the binomials - in it is the smallest lattice ideal containing them. Section 3.3, non_toric.in. -toric_ideal is an integer matrix with d columns. The object computed from the binomials - in it is the smallest toric ideal containing them and the toric ring whose defining ideal - the latter is. Section 3.2.1, toric_ideal.in. -normal_toric_ideal is an integer matrix with d columns. The object computed from the - binomials in it is the the normalization of the toric ring it defines. Section 3.2.2, - normal_toric_ideal.in. - - - -4.11. Unit vectors and unit matrix -A grading or a dehomogenization is often given by a unit vector: -unit_vector represents the n-th unit vector in Rd where n is the number given by . -This shortcut cannot be used as a row of a matrix. It can be used whenever a single vec- -tor is asked for, namely after grading, dehomogenization, signs and strict_signs. See -Section 2.5, rational.in. -The unit matrix can be given to every input type that expects a matrix: -unit_matrix - - - - -Example: - cone unit_matrix - -The number of rows is defined by amb_space and the type of the matrix, as usual. - - -4.12. Grading -This type is accessory. A Z-valued grading can be specified in two ways: - (1) explicitly by including a grading in the input, or - (2) implicitly. In this case Normaliz checks whether the extreme integral generators of the - monoid lie in an (affine) hyperplane A given by an equation λ (x) = 1 with a Z-linear - form λ . If so, then λ is used as the grading. - Implicit gradings are only possible for homogeneous computations. - If the attempt to find an implicit grading causes an arithmetic overflow and verbose has - been set (say, by the option-c), then Normaliz issues the warning - Giving up the check for a grading - - If you really need this check, rerun Normaliz with a bigger integer type. -Explicit definition of a grading: -grading is a vector of length d representing the linear form that gives the grading. Section 2.5, - rational.in. - _ -total degree represents a vector of length d with all entries equal to 1. Section 2.10, - Condorcet.in. -Before Normaliz can apply the degree, it must be restricted to the effective lattice E. Even if -the entries of the grading vector are coprime, it often happens that all degrees of vectors in E -are divisible by a greatest common divisor g > 1. Then g is extracted from the degrees, and it -will appear as denominator in the output file. -Normaliz checks whether all generators of the (recession) monoid have positive degree (after -passage to the quotient modulo the unit group in the nonpointed case). Vertices of polyhedra -may have degrees ≤ 0. - - -4.12.1. With binomial ideal input - -In this case the unit vectors correspond to generators of the monoid. Therefore the degrees -assigned to them must be positive. Moreover, the vectors in the input represent binomial -relations, and these must be homogeneous. In other words, both monomials in a binomial -must have the same degree. This amounts to the condition that the input vectors have degree -0. Normaliz checks this condition. - - - - -4.13. Dehomogenization -Like grading this is an accessory type. -Inhomogeneous input for objects in Rd is homogenized by an additional coordinate and then -computed in Rd+1 , but with the additional condition xd+1 ≥ 0, and then dehomogenizing all -results: the substitution xd+1 = 1 acts as the dehomogenization, and the inhomogeneous input -types implicitly choose this dehomogenization. -Like the grading, one can define the dehomogenization explicitly: -dehomogenization is a vector of length d representing the linear form δ . -The dehomogenization can be any linear form δ satisfying the condition δ (x) ≥ 0 on the cone -that is truncated. (In combination with constraints, the condition δ (x) ≥ 0 is automatically -satisfied since δ is added to the constraints.) -The input type dehomogenization can only be combined with homogeneous input types, but -makes the computation inhomogeneous, resulting in inhomogeneous output. The polyhedron -computed is the intersection of the cone C (and the lattice E) with the hyperplane given by -δ (x) = 1, and the recession cone is C ∩ {x : δ (x) = 0}. -A potential application is the adaptation of other input formats to Normaliz. The output must -then be interpreted accordingly. -Section 7.11, dehomogenization.in. - - -4.14. Weight vector for Gröbner bases -For the computation of Gröbner bases one can specify a weight vector by -gb_weight -It is a vecor with nonnegative entries for Lex as a tiebreaker and positive entries for RevLeX -(default choice). The length depends on the type of input. See Section 3.1.2 for a discussion -and examples. - - -4.15. Open facets -The input type open_facets is similar to strict_inequalities. However, it allows to apply -strict inequalities that are not yet known. This makes only sense for simplicial polyhedra -where a facet can be identified by the generator that does not lie in it. -open_facets is a vector with entries ∈ {0, 1}. -The restrictions for the use of open facets are the following: - (1) Only the input types cone, vertices and grading can appear together with open_facets. - (2) The vectors in cone are linearly independent. - (3) There is at most one vertex. -The number of vectors in cone may be smaller than d, but open_facets must have d entries. - - - -open_facets make the computation inhomogeneous. They are interpreted as follows. Let v -be the vertex—if there are no vertices, then v is the origin. The shifted C′ = v + C is cut -out by affine-linear inequalities λi (x) ≥ 0 with coprime integer coefficients. We number these -in such a way that λi (v + ci ) ̸= 0 for the generators ci of C (in the input order), i = 1, . . . , n. -Then all subsequent computations are applied to the shifted cone C′′ = v′ + C defined by the -inequalities - λi (x) ≥ ui -where the vector (u1 , . . . , ud ) is given by open_facets. (If dimC < d, then the entries u j with -j > dimC are ignored.) -That 1 indicates “open” is in accordance with its use for the disjoint decomposition; see Sec- -tion 7.14.2. Section 7.19 discusses an example. - - -4.16. Coordinates for projection -The coordinates of a projection of the cone can be chosen by -projection_coordinates It is a 0-1 vector of length d. -The entries 1 mark the coordinates of the image of the projection. The other coordinates give -the kernel of the projection. See Section 7.12 for an example. - - -4.17. Numerical parameters -Certain numerical parameters used by Normaliz can (only) be set in the input file. - - -4.17.1. Degree bound for series expansion - -It can be set by -expansion_degree -where is the number of coefficients to be computed and printed. See Section 7.10. - - -4.17.2. Number of significant coefficients of the quasipolynomial - -It can be set by -nr_coeff_quasipol -where is the number of highest coefficients to be printed. See Section 7.10.3. - - -4.17.3. Codimension bound for the face lattice - -It can be set by -face_codim_bound - - - - -where is the bound for the codimension of the faces to be computed. - - -4.17.4. Degree bounds for Markov and Gröbbner bases - -gb_degree_bound sets the upper bound for Markov and Gröbner bases, -gb_min_degree sets the lower bound for Markov and Gröbner bases. - - -4.17.5. Number of digits for fixed precision - -The computation of vilumes by signed decomposition can be done with a fixed precision. It is -et by -decimal_digits -where sets the precision to 10−n . - - -4.17.6. Block size for distributed computation - -See Appendix F.1 for an explanation. It is set by -block_size_hollow_tri - - - -4.18. Pointedness -Since version 3.1 Normaliz can also compute nonpointed cones and polyhedra without ver- -tices. - - -4.19. The zero cone -The zero cone with an empty Hilbert basis is a legitimate object for Normaliz. Nevertheless a -warning message is issued if the zero cone is encountered. - - - - -5. Computation goals and algorithmic variants -The library libnormaliz contains a class ConeProperties that collects computation goals, -algorithmic variants and additional data that are used to control the work flow in libnormaliz -as well as the communication with other programs. The latter are not important for the Nor- -maliz user, but are listed as a reference for libnormaliz. See Appendix D for a description of -libnormaliz. -All computation goals and algorithmic variants can be communicated to Normaliz in two -ways: - (1) in the input file, for example HilbertBasis, - (2) via a verbatim command line option, for example --HilbertBasis. -For the most important choices there are single letter command line options, for example -N -for HilbertBasis. The single letter options ensure backward compatibility to Normaliz 2. In -jNormaliz they are also accessible via their full names. -Some computation goals apply only to homogeneous computations, and some others make -sense only for inhomogeneous computations. -Some single letter command line options combine two or more computation goals, and some -algorithmic variants imply computation goals. -There are restrictions for algebraic polyhedra. See Section 8.3. - - -5.1. Default choices and basic rules -If several computation goals are set, all of them are pursued. In particular, computation goals -in the input file and on the command line are accumulated. But ---ignore, -i on the command line switches off the computation goals and algorithmic vari- - ants set in the input file. -The default computation goal is set if neither the input file nor the command line contains -a computation goal or an algorithmic variant that implies a computation goal. The deafault -computatin goal depends on the input type. - • Except the input of a monoid or binomial ideal it is - SupportHyperplanes + HilbertBasis + HilbertSeries . - In the homogeneous case, ClassGroup is included as well. - • For monoid, toric_ideal and normal_toric _ideal it is HilbertBasis + IsIntegrallyClosed - for the momnoid derived from them. - • For the input type lattice_ideal it is MarkovBasis. -If set explicitly in the input file or on the command line the following adds these computation -goals: -DefaultMode -DefaultMode can be set explicitly in addition to other computation goals. If it is set, implicitly - - - - -or explicitly, Normaliz will not complain about unreachable computation goals. - - -5.2. Computation goals -Almost always the computation goals set explicitly or by default require the comoputation of -auxiliary data that themselves can be asked for by explicit computation goals. In most cases -the results of these computations appear in the output. In case of doubt set exlicit computation -goals. - -5.2.1. Lattice data - -Sublattice, -S (upper case S) asks Normaliz to compute the coordinate transformation to - and from the efficient sublattice. - -5.2.2. Support hyperplanes and extreme rays - -SupportHyperplanes, -s triggers the computation of support hyperplanes and extreme rays. -Normaliz tries to find a grading in the homogeneous case. -VerticesFloat converts the format of the vertices to floating point. It implies SupportHyperplanes. - - -SuppHypsFloat converts the format of the support hyperplanes to floating point. It implies - SupportHyperplanes. -ExtremeRaysFloat does the same for the extreme rays. -Note that VerticesFloat and SuppHypsFloat are not pure output options. They are computa- -tion goals, and therefore break implicit DefaultMode. -ProjectCone Normaliz projects the cone defined by the input data onto a subspace generated - by selected coordinate vectors and computes the image with the goal SupportHyperplanes. - -5.2.3. Hilbert basis and lattice points - -HilbertBasis, -N triggers the computation of the Hilbert basis. In inhomogeneous compu- - tations it asks for the Hilbert basis of the recession monoid and the module generators. -WitnessNotIntegrallyClosed, -w With this option, Normaliz stops the Hilbert basis com- - putation as soon it has found a witness confirming that the original monoid is not inte- - grally closed. -Deg1Elements, -1 restricts the computation to the degree 1 elements of the Hilbert basis in - homogeneous computations (where it requires the presence of a grading). -LatticePoints is identical to Deg1Elements in the homogeneous case, but implies NoGradingDenom. - In inhomogeneous computations it is a synonym for HilbertBasis. -SingleLatticePoint stops the computation once a lattice point has been found. Forces the - project-and-lift algorithm. - - - -ModuleGeneratorsOverOriginalMonoid, -M computes a minimal system of generators of - the integral closure over the original monoid (see Section 7.18). Requires the existence - of original monoid generators. -The boolean valued computation goal IsIntegrallyClosed is also related to the Hilbert basis; -see Section 5.2.15. -HilbertBasis ExploitAutomsVectors and -Deg1Elements ExploitAutomsVectors exploit the automorphism group of the cone. - - -5.2.4. Enumerative data - -The computation goals in this section require a grading. They include SupportHyperplanes. -HilbertSeries,-q triggers the computation of the Hilbert series. -EhrhartSeries computes the Ehrhart series of a polytope, regardless of whether it is defined - by homogeneous or inhomogeneous input. In the homogeneous case it is equivalent - to HilbertSeries + NoGradingDenom, but not in the inhomogeneous case. See the - discussion in Section 7.1. Can be combined with HSOP. -Multiplicity, -v restricts the computation to the multiplicity. -Volume, -V computes the lattice normalized and the Euclidean volume of a polytope given - by homogeneous or inhomogeneous input (implies Multiplicity in the homogeneous - case, but also sets NoGradingDenom). -HSOP lets Normaliz compute the degrees in a homogeneous system of parameters and the - induced representation of the Hilbert or Ehrhart series series. Note that HSOP does not - imply HilbertSeries or EhrhartSeries. -NoPeriodBound This option removes the period bound that Normaliz sets for the computation - of the Hilbert quasipolynomial (presently 106 ). -NoQuasiPolynomial suppresses the out put of the quasipolynomial. -NumberLatticePoints finds the number of lattice points. They are not stored. -OnlyCyclotomicHilbSer restricts the output to the series representation with the cyclotomic - denominator. Includes NoQuasiPolynomial. - -5.2.5. Combined computation goals - -Can only be set by single letter command line options: - -n HilbertBasis + Multiplicity - -h HilbertBasis + HilbertSeries - -p Deg1Elements + HilbertSeries - - -5.2.6. The class group - -ClassGroup, -C is self explanatory, includes SupportHyperplanes. Not allowed in inhomo- - geneous computations. - - - -5.2.7. Integer hull - -IntegerHull, -H computes the integer hull of a polyhedron. Implies the computation of the - lattice points in it. -More precisely: in homogeneous computations it implies Deg1Elements, in inhomogeneous -computations it implies HilbertBasis. See Section 2.14. - - -5.2.8. Triangulation and Stanley decomposition - -Triangulation, -T makes Normaliz compute, store and export the full triangulation. -ConeDecomposition, -D Normaliz computes a disjoint decomposition of the cone into semi- - open simplicial cones. Implies Triangulation. -TriangulationSize, -t makes Normaliz count the simplicial cones in the full triangulation. -TriangulationDetSum makes Normaliz additionally sum the absolute values of their deter- - minants. -StanleyDec, -y makes Normaliz compute, store and export the Stanley decomposition. -AllGeneratorsTriangulation makes Normaliz compute and store a triangulation that uses - all generators. -LatticePointTriangulation makes Normaliz compute and store a triangulation that uses all - lattice points in a polytope. -UnimodularTriangulation makes Normaliz compute and store a unimodular triangulation. -The triangulation and the Stanley decomposition are treated separately since they can become -very large and may exhaust memory if they must be stored for output. -Note that these decompositions cannot be computed for a polyhedron that is unbounded (mod- -ulo its maximal subspace). However, they are allowed for polytopes defined by inhomoge- -neous input. UnimodularTriangulation is only allowed in homogeneous computations and -is excluded for algebraic polyhedra. -The following triangulations are defined by the order of the generators. See SEctions 7.15.5 -and 7.15.6. -PlacingTriangulation -PullingTriangulation - - -5.2.9. Face structure - -The f-vector of a polyhedron is computed by -FVector -The set of faces of a polyhedron is computed by -FaceLattice -Like the triangulation or Stanley decomposition the face lattice can become very large, and it -is already computed with FVector. FaceLattice writes an extra output file. The details of its - - - -representation in the extra output file are discussed in Section 7.17. -The face lattice computation is based on the incidence vectors of the facets. It is possible to -retrieve this matrix (independently of FVector or FaceLattice) via the computation goal -Incidence -Section 7.17 as well. See it also for the dual versions -DualFVector -DualFaceLattice -DualIncidence -For computation of orbits we have -FVectorOrbits -FaceLatticeOrbits -DualFVectorOrbits -DualFaceLatticeOrbits - - -5.2.10. Semiopen polyhedra - -IsEmptySemiopen -asks for the emptiness of a semiopen polyhedron. See Section 7.20. - - -5.2.11. Automorphism groups - -Automorphism groups are defined in Section 7.22. -Automorphisms computes the integral automorphisms of rational polyhedra and the algebraic - automorphisms of algebraic polytopes. -RationalAutomorphisms computes the rational automorphisms of rational polytopes. -EuclideanAutomorphisms computes the euclidean automorphisms of rational and algebraic - polytopes. -CombinatorialAutomorphisms computes ate combinatorial automorphisms of polyhedra. -AmbientAutomorphisms computes automorphisms induce by permutations of coordinates of - the ambient space. -InputAutomorphisms computes taional (or algebraic) automorphisms based solely on the in- - put and initial coordinate transformations. - - -5.2.12. Weighted Ehrhart series and integrals - -WeightedEhrhartSeries, -E makes Normaliz compute a generalized Ehrhart series. -VirtualMultiplicity, -L makes Normaliz compute the virtual multiplicity of a weighted - Ehrhart series. -Integral, -I makes Normaliz compute an integral over a polytope. Implies NoGradingDenom. - - - - -These computation goals require a homogeneous computation. -Don’t confuse these options with symmetrization. The latter symmetrizes (if possible) the -given data and uses -E or -L internally on the symmetrized object. The options -E,-I,-L ask -for the input of a polynomial. See Section 4.1.8. - - -5.2.13. Markov and Gröbner bases - -They are discussed in Section 3. -MarkovBasis computes a system of generators for a toric ideal defining a monoid or a lattice - ideal. -GroebnerBasis computes a system of generators for such ideals. -Representations compites the represenztation of the reducible elements in a generating sys- - tem of an affine monoid by the Hilbert basis. - Lex sets the lexicographic monomial order for Gröbner bases, -RevLex sets the degree reverse lexicographic order, -DegLex sets the degree lexicographic order. - - -5.2.14. Local structure - -SingularLocus comoputes the singular locus of an affine monoid (algebra), -CodimSingularLocus computes its codimension. - - -5.2.15. Boolean valued computation goals - -They tell Normaliz to find out the answers to the questions they ask. Two of them are more -important than the others since they may influence the course of the computations: -IsIntegrallyClosed : is the original monoid integrally closed? Normaliz stops the Hilbert - basis computation as soon as it can decide whether the original monoid contains the - Hilbert basis (see Section 2.11.1). Normaliz tries to find the answer as quickly as pos- - sible. This may include the computation of a witness, but not necessarily. If you need a - witness, use WitnessNotIntegrallyClosed, -w. -IsSerreR1 checks the Serre property (R1 ) for ffine monoids (automatically satisfied by nor- - mal monoids). -IsPointed : is the efficient cone C pointed? This computation goal is sometimes useful to - give Normaliz a hint that a nonpointed cone is to be expected. See Section 7.13.3. -For the following we only need the support hyperplanes and the lattice: -IsGorenstein, -G : is the monoid of lattice points Gorenstein? In addition to answering - this question, Normaliz also computes the generator of the interior of the monoid (the - canonical module) if the monoid is Gorenstein. (Only in homogeneous computations.) -The remaining ones: - - - - -IsDeg1ExtremeRays : do the extreme rays have degree 1? (Only in homogeneous computa- - tions.) -IsDeg1HilbertBasis : do the Hilbert basis elements have degree 1? (Only in homogeneous - computations.) -IsReesPrimary : for the input type rees_algebra, is the monomial ideal primary to the irrel- - evant maximal ideal? -IsLatticeIdealToric asks whether the lattice ideal in the input is actually toric -The last three computation goals are not really useful for Normaliz since they will be answered -automatically. Note that they may trigger extensive computations. - - -5.2.16. Fusion rings - -See Appendix H. - - -5.3. Integer type -There is no need to worry about the integer type chosen by Normaliz. All preparatory com- -putations use infinite precision. The main computation is then tried with 64 bit integers. If it -fails, it will be restarted with infinite precision. -Infinite precision does not mean that overflows are completely impossible. In fact, Normaliz -requires numbers of type “degree” fit the type long (typically 64 bit on 64 bit systems). If an -overflow occurs in the computation of such a number, it cannot be remedied. -The amount of computations done with infinite precision is usually very small, but the trans- -formation of the computation results from 64 bit integers to infinite precision may take some -time. If you need the highest possible speed, you can suppress infinite precision completely -by -LongLong -With this option, Normaliz cannot restart a failed computation. LongLong is not a cone prop- -erty. -On the other hand, the 64 bit attempt can be bypassed by -BigInt, -B -Note that Normaliz tries to avoid overflows by intermediate results (even if LongLong is set). -If such overflow should happen, the computation is repeated locally with infinite precision. -(The number of such GMP transitions is shown in the terminal output.) If a final result is too -large, Normaliz must restart the computation globally. -Caveat. The overflow check of Normaliz is not an absolute guarantee. The probability that it -fails is microscopically small, but failure is not totally excluded. Very critical computations -for which one has no other confirmation should be redone in BigInt. -Normaliz tries to improve bases of sublattices by LLL reduction. This is an arithmetically -risky operation, even with BigInt. In case you experience any problems, like a floating point - - - -exception “division by zero”, use -NoLLL -Once it has been used once ro a cone in libnormaliz, it is set for all subsequent computations. -To see the problem just described, run overflow.in with and without NoLLL. - - -5.4. The choice of algorithmic variants -For its main computation goals Normaliz has algorithmic variants. It tries to choose the variant -that seems best for the given input data. This automatic choice may however be a bad one. -Therefore the user can completely control which algorithmic variant is used. - -5.4.1. Primal vs. dual - -For the computation of Hilbert bases Normaliz has two algorithms, the primal algorithm that -is based on triangulations, and the dual algorithm that is of type “pair completion”. We have -seen both in Section 2. Roughly speaking, the primal algorithm is the first choice for generator -input, and the dual algorithm is usually better for constraints input. The choice also applies to -the computation of degree 1 elements. However, for them the default choice is project-and-lift -(well, almost always). See Section 7.2.1. The conditions under which the dual algorithm is -chosen are specified in Section 7.5. -The choice of the algorithm can be fixed or blocked: -DualMode, -d activates the dual algorithm for the computation of the Hilbert basis and de- - gree 1 elements. Includes HilbertBasis, unless Deg1Elements is set. It overrules - IsIntegrallyClosed. -PrimalMode, -P blocks the use of the dual algorithm. -The automatic choice can of course fail. See Section 7.5 for an example for which it is bad. - -5.4.2. Lattice points in polytopes - -For this task Normaliz has several methods. They are discussed in Section 7.2. The default -choice is the project-and-lift algorithm. It can be chosen explicitly: -Projection, -j -NoProjection blocks it. -Alternative choices are -ProjectionFloat, -J , project-and-lift with floating point arithmetic, -PrimalMode, -P , triangulation based method, -Approximate, -r , approximation of rational polytopes followed by triangulation and -DualMode, -d , dual algorithm. -Note: none of these algorithmic variants implies the computation of the lattice points. They -must be asked for by a computation goal. - - - -The following options modify Projection and ProjectionFloat: -NoLLL blocks the use of LLL reduced coordinates, -NoRelax blocks relaxation. -Both LLL and relaxation are switched on by default. See Section 7.2.3. -For positive systems (see Section 7.2.4) Normaliz chooses “coarse projection”, and it may use -a patching variant of project-and-lift. These choices can be blocked by -NoCoarseProjection -NoPatching -Moreover, there are further options by which the order, in which the “patches” are processed, -can be influenced. See Section 7.2.6. - - -5.4.3. Bottom decomposition and order - -Bottom decomposition is a way to produce an optimal triangulation for a given set of genera- -tors. It is discussed in Section 7.3. The criterion for its automatic choice is explained there. It -can be forced or blocked: -BottomDecomposition, -b tells Normaliz to use bottom decomposition in the primal algo- - rithm. -NoBottomDec, -o forbids Normaliz to use bottom decomposition in the primal algorithm, - even if it would otherwise be chosen because of large roughness (see Section 7.3). -An option to be mentioned in this context is -KeepOrder, -k forces Normaliz to insert the generators (for generator input) or the inequal- - ities (for constraint input) in the input order. This option is useful if the input has been - produced in a systematic order that would be destroyed by the degree-lexicogrpahic - order applied by Normaliz. Also blocks BottomDecomposition. - - -5.4.4. Multiplicity, volume and integrals - -For the computation of multiplicities Normaliz offers has three main algorithms: - (1) the computation and evaluation of a full triangulation, - (2) descent in the face lattice, - (3) signed decomposition. -These are described in more detail in Section 7.6. Moreover, one can use symmetrization (see -below), and (2) has a variant using isomorphism types. -Normaliz tries them by default in the order signed decoposition, descent, symmetritation and -uses the first for which the default conditions are satisfied (as long as there is no need to -compute a full triangulation for other reasons). The last resort is (1). -The options asking explicitly for an algorithm or excluding it are -Descent, -F - - - - -NoDescent -SignedDec -NoSignedDec -The variant using isomorphism types can be activated by -Descent ExploitIsosMult -You van ask for -StrictTypeChecking -if you don’t btrust SHA256 hash values. See Section 7.6.3. -Another option to be mentioned in this context is -FixedPrecision -It can be applied if the multiplicity is computed by signed decomposition. See Section 7.6.5 -For integrals one can chose either the standard triangulation or signed decomposition. In the -latter case FixedPrecision is also available. -If one wants to compute multiplicities (or volumes) with signed decomposition, one can use -distributed computation on a HPC. Distributed computation is described in Appendix F.1. - - -5.4.5. Symmetrization - -In rare cases Normaliz can use symmetrization in the computation of multiplicities or Hilbert -series. If applicable, this is a very strong tool. We have mentioned it in Section 2.10 and will -discuss it in Section 7.8. It will be chosen automatically, but can also be forced or blocked: -Symmetrize, -Y lets Normaliz compute the multiplicity and/or the Hilbert series via sym- - metrization (or just compute the symmetrized cone). -NoSymmetrization blocks symmetrization. -The integration involved in symmetrization can be done by signed decomposition. - - -5.4.6. Options for the grading - -By setting -NoGradingDenom -you can force Normaliz not to change the original grading if it would otherwise divide it -by the grading denominator. It is implied by several computation goals for polytopes. See -Section 7.1. -NoGradingDenom is set automatically inn inhomogeneous computations. -By -GradingIsPositive -the user guarantees that the grading is positive. This option can be useful in rare cases if -Normaliz would otherwise compute extreme rays only to check the positivity of the grading. - - - -5.5. Control of computations and communication with interfaces -In addition to the computation goals in Section 5.2, the following elements of ConeProperties -control the work flow in libnormaliz and can be used by programs calling Normaliz to ensure -the availability of the data that are controlled by them. -OriginalMonoidGenerators controls the generators of the original monoid. -ModuleGenerators controls the module generators in inhomogeneous computation. -ExtremeRays controls the extreme rays. -VerticesOfPolyhedron controls the vertices of the polyhedron in the inhomogeneous case. -MaximalSubspace controls the maximal linear subspace of the (homogenized) cone. -EmbeddingDim controls the embedding dimension. -Rank controls the rank. -RecessionRank controls the rank of the recession monoid in inhomogeneous computations. -AffineDim controls the affine dimension of the polyhedron in inhomogeneous computations. -ModuleRank in inhomogeneous computations it controls the rank of the module of lattice - points in the polyhedron as a module over the recession monoid. -ExcludedFaces controls the excluded faces. -InclusionExclusionData controls data derived from the excluded faces. -Grading controls the grading. -GradingDenom controls its denominator. -Dehomogenization controls the dehomogenization. -ReesPrimaryMultiplicity controls the multiplicity of a monomial ideal, provided it is pri- - mary to the maximal ideal generated by the indeterminates. Used only with the input - type rees_algebra. -EuclideanVolume controls the Euclidean volume. -GeneratorOfInterior controls the generator of the interior if the monoid is Gorenstein. -CoveringFace asks for an excluded face making the semiopen polyhedron empty. -Equations controls the equations. -Congruences controls the congruences. -ExternalIndex controls the external index. -InternalIndex controls the internal index. -UnitGroupIndex controls the unit group index. -IsInhomogeneous controls the inhomogeneous case. -HilbertQuasiPolynomial controls the Hilbert quasipolynomial. -EhrhartQuasiPolynomial controls the Ehrhart quasipolynomial. -WeightedEhrhartQuasiPolynomial controls the weighted Ehrhart quasipolynomial. -IsTriangulationNested controls the indicator of this property. -IsTriangulationPartial similar. -NoSubdivision blocks pyramid decomposition and sudivision of simplices in primal mode. -BasicTriangulation used for the computation of trianglations. itemtt[BasicStanleyDec] the - same for Stanley decompositions. -PullingTriangulationInternal used for the computation of pulling triangulations. - - - - -SingleLatticePointInternal quite obvious. - - - -5.6. Rational and integer solutions in the inhomogeneous case -The integer solutions of a homogeneous diophantine system generate the rational solutions as -well: every rational solution has a multiple that is an integer solution. Therefore the rational -solutions do not need an extra computation. If you prefer geometric language: a rational cone -is generated by its lattice points. -This is no longer true in the inhomogeneous case where the computation of the rational solu- -tions is an extra task for Normaliz. This extra step is inevitable for the primal algorithm, but -not for the dual algorithm. In general, the computation of the rational solutions is much faster -than the computation of the integral solutions, but this by no means always the case. -Therefore we have decoupled the two computations if the dual algorithm is applied to inho- -mogeneous systems or to the computation of degree 1 points in the homogeneous case. The -combinations -DualMode HilbertBasis, -dN -DualMode Deg1Elements, -d1 -DualMode ModuleGenerators -DualMode LatticePoints -do not imply the computation goal SupportHyperplanes (and not even Sublattice) which -would trigger the computation of the rational solutions (geometrically: the vertices of the -polyhedron). If you want to compute them, you must add one of -SupportHyperplanes, -s -ExtremeRays -VerticesOfPolyhedron -The last choice is only possible in the inhomogeneous case. Another possibility in the inho- -mogeneous case is is to use DualMode without a restriction. -If Projection or ProjectionFloat is used for parallelotopes defined by inequalities, then -Normaliz does not compute the vertices, unless asked for by one of the three computation -goals just mentioned or the extreme rays are needed for some other computation. The same -holds if the volume of a parallelotope is computed. - - -6. Running Normaliz -The standard form for calling Normaliz is - normaliz [options] -where is the name of the project, and the corresponding input file is .in. -Note that normaliz may require to be prefixed by a path name, and the same applies to -. A typical example on a Linux or Mac system: - - - - - ./normaliz --verbose -x=5 example/big -that for MS Windows must be converted to - .\normaliz --verbose -x=5 example\big -Normaliz uses the standard conventions for calls from the command line: - (1) the order of the arguments on the command line is arbitrary. - (2) Single letter options are prefixed by the character - and can be grouped into one string. - (3) Verbatim options are prefixed by the characters --. -The options for computation goals and algorithmic variants have been described in Section 5. -In this section the remaining options for the control of execution and output are discussed, -together with some basic rules for the use of the options. - - -6.1. Basic rules -The options for computation goals and algorithms variants have been explained in Section 5. -The options that control the execution and the amount of output will be explained in the -following. Basic rules for the use of options: - 1. If no is given, the program will terminate. - 2. The option -x differs from the other ones: in -x= represents a positive number - assigned to -x; see Section 6.3. - 3. Similarly the option --OutputDir= sets the output directory; see 6.7. - 4. Normaliz will look for .in as input file. - If you inadvertently typed rafa2416.in as the project name, then Normaliz will first - look for rafa2416.in.in as the input file. If this file doesn’t exist, rafa2416.in will be - loaded. - 5. The options can be given in arbitrary order. All options, including those in the input - file, are accumulated, and syntactically there is no mutual exclusion. However, some - options may block others during the computation. For example, KeepOrder blocks - BottomDecomposition. - 6. If Normaliz cannot perform a computation explicitly asked for by the user, it will termi- - nate. Typically this happens if no grading is given although it is necessary. - 7. In the options include DefaultMode, Normaliz does not complain about missing data - (anymore). It will simply omit those computations that are impossible. - 8. If a certain type of computation is not asked for explicitly, but can painlessly be produced - as a side effect, Normaliz will compute it. For example, as soon as a grading is present - and the Hilbert basis is computed, the degree 1 elements of the Hilbert basis are selected - from it. - In addition to computing a single file per run, Normaliz can also process a list of input - files. See Section G. - - - - -6.2. Info about Normaliz ---help, -? displays a help screen listing the Normaliz options. ---version displays information about the Normaliz executable. - - - -6.3. Control of execution -The options that control the execution are: ---verbose, -c activates the verbose (“console”) behavior of Normaliz in which Normaliz - writes additional information about its current activities to the standard output. ---talk gives more output than verbose (at present only implemented in the patching variant - of project-and-lift) --x= Here stands for a positive integer limiting the number of threads that Normaliz is - allowed access on your system. The default value is 8. (Your operating system may set - a lower limit). - -x=0 switches off the limit set by Normaliz. - If you want to run Normaliz in a strictly serial mode, choose -x=1. -parallel_threads can be used in the input file instead. -The number of threads can also be controlled by the environment variable OMP_NUM_THREADS. -See Section 10.1 for further discussion. -If there ar5e many polynomials in the input it can be difficult to find an error in them. As a -help ion such cases one can say -list_polynomials -The last polynomial listed has caused the error. - - -6.4. Interruption -During a computation normaliz can be interrupted by pressing Ctrl-C on the keyboard. If this -happens, Normaliz will stop the current computation. If you want to see the results already -computed, ask for -OutputOnInterrupt, --OOU -Can be set in the input file or on the command line as a long option. -If Ctrl-C is pressed during the output phase, Normaliz is stopped immediately. - - -6.5. Stopping a computation -If Normaliz is running in the background and cannot be interrupted by CTrl-C, then one can -stop it by inserting a file -normaliz.stop - - - - -into the working directory. This will stop (possibly with some delay) the instances of normaliz -running in that directory. In order to stop a specific instance, use -.stop - - - -6.6. Time bound -In order to set a time bound for the execution of Normaliz one creates a file -normaliz.time -in the working directory. It contains a single floating number that bounds the wall clock time -of Normaliz. At present it is only implemented in the project-and-lift algorithm for lattice -points. - - -6.7. Control of output files -In the default setting Normaliz writes only the output file .out (and the files pro- -duced by Triangulation, StanleyDec and FaceLattice). The amount of output files can be -increased as follows: ---files, -f Normaliz writes the additional output files with suffixes gen, cst, and inv, pro- - vided the data of these files have been computed. ---all-files, -a includes Files, Normaliz writes all available output files (except typ and - those that are automatically written by computation goals). --- chooses the output file with suffix . -For the list of potential output files, their suffixes and their interpretation see Section 9. There -are several options --. -If the computation goal IntegerHull is set, Normaliz computes a second cone and lattice. -The output is contained in .IntHull.out. The options for the output of -are applied to .IntHull as well. There is no way to control the output of the two -computations individually. -Similarly, if symmetrization has been used, Normaliz writes the file .symm.out. It -contains the data of the symmetrized cone. -Sometimes one wants the output to be written to another directory. The output directory can -be set by ---OutputDir= . The path is an absolute path or a path relative to the - current directory (which is not necessarily the directory of .in.) -Note that all output files will be written to the chosen directory. It must be created before -Normaliz is started. -Extreme rays and vertices may have very long integer coordinates. One can suppress their -output by -NoExtRaysOutput - - - - -For similar reasons one may want to suppress the output of support hyperplanes, namely by -NoSuppHypsOutput -Similarly, -NoHilbertBasisOutput -supprsesses thze output of Hilbert bases and latticec points. An even more drastic option is -NoMatricesOutput -It suppresses all output after the “preamble”. It is useful in testing large examples where the -numbers of extreme rays, lattice points etc. are usually a good criterion for correctness. -NoExtRaysOutput, NoSuppHypsOutputand NoMatricesOutput are not cone properties. -BinomialsPacked chooses a packed format for files containing binomials. See Section 7.25. - - - -6.8. Ignoring the options in the input file -Since Normaliz accumulates options, one cannot get rid of settings in the input file by com- -mand line options unless one uses ---ignore, -i This option disables all options in the input file. - - - - diff --git a/apn/lean/docs/plantri/LICENSE b/apn/lean/docs/plantri/LICENSE deleted file mode 100644 index d6456956..00000000 --- a/apn/lean/docs/plantri/LICENSE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/apn/lean/docs/plantri/plantri-guide.txt b/apn/lean/docs/plantri/plantri-guide.txt deleted file mode 100644 index c21907cc..00000000 --- a/apn/lean/docs/plantri/plantri-guide.txt +++ /dev/null @@ -1,1579 +0,0 @@ - - -Guide to using plantri (version 5.5) -==================================== - -Gunnar Brinkmann - University of Gent - Gunnar.Brinkmann@ugent.be - -Brendan McKay - Australian National University - brendan.mckay@anu.edu.au - -Heidi Van den Camp - - -INTRODUCTION. - - plantri is a program that generates certain types of graphs that are - embedded on the sphere. - - Exactly one member of each isomorphism class is output, using an amount - of memory almost independent of the number of graphs produced. This, - together with the exceptionally fast operation and careful validation, - makes the program suitable for processing very large numbers of graphs. - - Isomorphisms are defined with respect to the embeddings, so in some - cases outputs may be isomorphic as abstract graphs. Formal definitions - of isomorphism of embedded graphs are below. - - In this document we adopt the common distinction between a "plane graph" - (a graph embedded on the sphere without edge crossings) and a "planar - graph" (an abstract graph which has at least one such embedding). - -DEFINITIONS. - - When a graph is drawn on the sphere without edges crossing, the sphere is - thereby divided into regions called FACES. If the graph is connected, each - face is homeomorphic to a disk (which in this case just means that it has - no holes). We can cut a hole in the sphere in the middle of a face and - open the sphere into a plane, but we must remember that the outside region - is as much a face as the other regions even though it is no longer a disk. - - The combinatorial structure of a graph drawn on the sphere is represented - by the cyclic order of the edges at each vertex, where (according to the - arbitrary choice we will adopt) the order is clockwise if we look at - the sphere from the outside. - - a - 3------------4 - / \ /| - / \ b c / | - d / \ / | e FIGURE 1. - / \ / | - / \ / | - 0 --------- 2 ---- 1 - f g - - In the above example, the abstract graph is given by the edges - a={3,4}, b={2,3}, c={2,4}, d={0,3}, e={1,4}, f={0,2}, g={1,2}. - The embedding is given by listing the edges in clockwise order for - each vertex: - 0: d,f 1: e,g 2: b,c,g,f 3: a,b,d 4: a,e,c - Note that the cyclic order b,c,g,f is the same as c,g,f,b - the - starting point doesn't matter. - - To fully represent the embedded graph we need both the abstract graph - and the cyclic edge orders. In the case of a graph with no parallel - edges (more than one edge with the same endpoints), it is conventional - to give both at once by listing neighbours in clockwise order: - 0: 2,3 1: 2,4 2: 0,3,4,1 3: 0,4,2 4: 1,2,3 - Later we will describe a convention for representing even embeddings of - some graphs with parallel edges by cyclic neighbour lists. - - The MIRROR IMAGE of an embedded graph is obtained by reversing all the - cyclic orders. That corresponds to turning the sphere inside out. - The mirror image of the above graph is - - a - 4------------3 - |\ / \ - | \ c b / \ - e | \ / \ d FIGURE 2. - | \ / \ - | \ / \ - 1---- 2 ---------- 0 - g f - - In defining "isomorphism" for two embedded graphs, we have the choice of - whether or not to automatically regard a graph and its mirror image as - isomorphic. plantri knows both definitions: - - Let G and H be two connected embedded graphs with the same numbers of - vertices and the same number of edges. - - An ORIENTATION-PRESERVING (O-P) ISOMORPHISM from G to H is a bijection fv - from V(G) to V(H), and a bijection fe from E(G) to E(H), such that - (1) If e = {v1,v2} is in E(G), then fe(e) = {fv(v1),fv(v2)} and fe(e) - is in E(H). - (2) If (e1,e2,...,ek) is the set of edges incident with a vertex v of G, - in clockwise order, then (fe(e1),fe(e2),...,f(ek)) is the set of - edges incident with the vertex fv(v) of G, in clockwise order. - - An ORIENTATION-REVERSING (O-R) ISOMORPHISM from G to H is a bijection fv - from V(G) to V(H), and a bijection fe from E(G) to E(H), such that - (1) If e = {v1,v2} is in E(G), then fe(e) = {fv(v1),fv(v2)} and fe(e) - is in E(H). - (2) If (e1,e2,...,ek) is the set of edges incident with a vertex v of G, - in clockwise order, then (fe(e1),fe(e2),...,f(ek)) is the set of - edges incident with the vertex fv(v) of G, in anti-clockwise order. - - Note that the two definitions differ only in the penultimate word. - - An ISOMORPHISM from G to H is either an O-P isomorphism or an O-R - isomorphism. Isomorphism and O-P isomorphism (but not O-R isomorphism) - are equivalence relations, so we can speak of ISOMORPHISM CLASSES and - O-P ISOMORPHISM CLASSES. Similarly, the set of all isomorphisms and - the set all O-P isomorphisms (but not the set of all O-R isomorphisms) - from an embedded graph to itself form groups under composition: the - AUTOMORPHISM GROUP and the O-P AUTOMORPHISM GROUP. - - As is well known, ISOMORPHISM of two embedded graphs is the same as - abstract isomorphism in the case that the graphs are 3-connected. - However, if a graph is not 3-connected, its embeddings may or may not - be isomorphic. Figure 3 shows two non-isomorphic embeddings of the - same abstract graph. - - ---------- ---------- _____ - |\ /| |\ | - | \ / | | \ | FIGURE 3. - | \ / | | \ | - | | | | - ---------- ---------- - - Given an embedded graph G, we can form another embedded graph called its - PLANAR DUAL (or just DUAL) D. The vertices of D are the faces of G. - The edges of D are in 1-1 correspondence with the edges of G: the - two endpoints of an edge in D are the faces that are on either side of - the corresponding edge in G. Finally, the cyclic order of edges around - a vertex in D (which is a face in G) is the clockwise order of the - corresponding edges bounding the face in G. The graph in Figure 2 has - the following dual: - - ---------------------- - | d | - | ---------- | - | / a | | - | / C------ D - | / c / b | - |/ e / | FIGURE 4. - A --------- B | - |\ g | | - | ---------- | - | f | - ---------------------- - - The vertex A corresponds to the outside face of Figure 2. Note that the - faces of the dual correspond to the vertices of the original graph. In - fact, it is not hard to see that the dual of the dual of an embedded - graph is the original graph. Also note how the existence of vertices of - degree 2 in the original graph led to parallel edges in the dual. - - If all the faces of an embedded graph are triangles (i.e. bounded by 3 - edges) the embedded graph is called a TRIANGULATION. The literature - is divided over whether the outside face must be a triangle, but we will - take it that ALL faces are triangles. The dual of a triangulation is an - embedded cubic (trivalent) graph. A triangulation with n vertices has - exactly 3n-6 edges and 2n-4 faces. - - A graph (embedded or not) is k-CONNECTED if it cannot be disconnected by - removing fewer than k vertices. It is convenient to revise the definition - slightly for the complete graph K4: it is 3-connected but not 4-connected. - A standard theorem says that a triangulation is 3-connected if and only - if it has no loops or parallel edges. It is impossible for a planar - graph to be k-connected for k greater than 5. - - A graph (embedded or not) is CYCLICALLY K-CONNECTED if it is impossible - to remove k or fewer vertices so that the graph breaks into components of - which at least two have cycles. As before, K4 is defined to be cyclically - 3-connected but not cyclically 4-connected. Planar graphs can have - arbitrarily high cyclic connectivity. - - In many circumstances there are relationships between the connectivity of - an embedded graph and the cyclic connectivity of its dual. For example, - a triangulation is k-connected if and only if its dual is cyclically - k-connected. - - A SIMPLE graph is one with no parallel edges or loops. - - -INSTALLING plantri. - - The latest edition of plantri can be obtained from - http://cs.anu.edu.au/~bdm/plantri - - plantri.c is a C program written as a single file plantri.c. It should - compile immediately with most modern C compilers, as it only contains - code that is very standard (unless your compiler is VERY old). - - To compile plantri.c under Unix, you can use - cc -o plantri -O4 plantri.c - where "4" is the highest number your compiler accepts, or just - make plantri (but check makefile first). - -RUNNING plantri. - - To run plantri, you need to be able to enter command-line parameters. - All our examples will use standard Unix syntax. - - An example of a plantri run is: - plantri -d 16 - which makes the duals (because -d is present) of the 3-connected - triangulations with 16 vertices. In other words, it makes the - 3-connected cubic plane graphs with 28 vertices. - - The only compulsory parameter is the number of vertices ("16" in the - example). This can also be given as "28d" (the suffix 'd' means 'dual') - in which case it is converted by adding 4 then dividing by 2: - (28+4)/2 = 16. In the case of triangulations, this calculation yields - the number of faces, which is the number of vertices in the dual cubic - graph. - - Apart from the one compulsory parameter, there are three types of optional - parameters: - - * SWITCHES are introduced by a '-' character. If there are more than one - they can be arbitrarily concatenated or separated. They can also appear - anywhere. For example, these command lines are all equivalent: - plantri -m4u 10 - plantri -u -m4 10 - plantri 10 -um4 - plantri -u 10 -m4 - The meanings of the switches are explained in the next sections. - In the case of a switch taking a numerical value, such as -m, giving - it without a value is the same as giving value 0. That is, -m is - the same as -m0 . - - * An OUTPUT FILE can be given, if you want the graphs to be sent somewhere - other than standard output. Information other than graphs (such as - statistics) is written to the standard error stream. It is permitted - to use a lonely '-' to explicitly request graph output to standard - output. Example: - plantri 20 tri.20 --Send 20-vertex triangulations to file tri.20 - - * A RES/MOD pair can be given to select only a portion of the graphs that - would otherwise be produced. This pair comprises two integers with - '/' between, such as 13/100. The first integer can be from 0 to one - less than the second number. This example selects portion 13 from - portions 0, 1, ..., 99. In total, these 100 portions will be a - partition of all the graphs into 100 roughly equal parts. This is - provided to enable you to divide your computing task into pieces of - manageable size. - More information on RES/MOD pairs is given later. - - Parameters and switches may appear in any order with one exception: - the compulsory parameter (number of vertices) must precede any - output file or res/mod parameters. - -OUTPUT FORMATS. - - plantri can write graphs in a variety of different formats. - - PLANAR CODE is the default format. It is the preferred format if you plan - to feed the graph into a program that needs the embedding, and also - convenient if you don't need the embedding. However, it uses characters - which are not printable so it is not suitable for looking at by eye. - - ASCII CODE is a human-readable version of planar code. The vertices of - the graph are named by ASCII characters starting with 'a'. Example: - 7 bcdefg,agfdc,abd,acbfe,adf,aedbg,afb - This is a graph with 7 vertices a,b,c,d,e,f,g. The neighbours of - 'a' in clockwise order are b,c,d,e,f,g; and so on. Each graph occupies - one line of output. Ascii code is convenient if you just want to draw - a few graphs by hand. - To select ascii code use -a. - - EDGE CODE is an alternative for planar code that enables all plane graphs - to be encoded unambiguously even if there are multiple loops. - See Appendix B for the full definition. To select edge code use -E. - - DOUBLE CODE is a human-readable version of edge code, with both the - primal and dual graphs appearing on the same line. It begins with - the number of vertices, and then for each vertex a list of the - incident edges is given in clockwise order. Then there is the number - of faces and a list of the edges of each face in clockwise order. - The names of the edges are A, B, C, and so on in ascii order. - An example is - 8 AHB BLC CJD DIE EFA FIG GKH JLK 6 ABCDE AFGH EIF DJKGI KLBH LJC - which is an 8-vertex cubic graph with edges A..L, and its 6 faces. - To select double code use -T. - - GRAPH6 is a compact code for the abstract structure of a graph. - The embedding is not represented, so this is not a suitable code to - use if you want the embedding. It is also restricted to simple - graphs. graph6 is one of the formats supported by Brendan McKay's - 'nauty' package. Each graph occupies one line. - To select graph6 code use -g. - - SPARSE6 is a compact code for the abstract structure of a graph which is - optimized for sparse graphs. If you don't want the embedding and are - dealing with cubic graphs of 20 or more vertices, sparse6 is a good - choice. sparse6 is one of the formats supported by Brendan McKay's - 'nauty' package. Each graph occupies one line. - To select sparse6 code use -s. - - Each of those formats except for ascii code also has a standard header, - which may be written to the output at the beginning: - - format header written by default? - - planar code >>planar_code<< yes - edge code >>edge_code<< yes - graph6 >>graph6<< no - sparse6 >>sparse6<< no - - In each case the header is written with no end-of-line characters after - it (for portability reasons). To write a header when the default is not - to, or vice-versa, use -h. - - If you only want to count the graphs and not write them, use -u to - select no output. - - Details of these formats is given in Appendices A-C. - -MISCELLANEOUS SWITCHES. - - -d causes the dual graph to be written instead of the original graph. - Note that it is applied only at the output stage. All other switches - refer to the original graph before the dual is taken. For example, - -m4 (minimum degree at least 4) refers to the original graph and - not to the dual. - - -o Normally, one member of each isomorphism class is written. If this - switch is given, one member of each O-P isomorphism class is written. - Since graph6 and sparse6 formats don't encode the embedding anyway, - this switch is ignored for output purposes if you use -g or -s. - -o also implies -G. - - -G This switch is only of interest if you are using a plug-in (see - Appendix D). It ensures that the full automorphism group is - computed for each output graph. If you are not using a plug-in, - -G will just slow things down. - - -V Only output graphs with non-trivial group. If -o is given, the - O-P group is used. Otherwise, the full group. Implies -G. - - -v plantri will always tell you (by a message to standard error) the - number of graphs that were produced. If you specify -v, it might - tell you some additional statistical information. For example, if - you use -o, -v will cause it to also inform you of the number of - isomorphism classes as well as the number of isomorphism classes - which are O-P isomorphic to their mirror images. - -SELECTING THE GRAPH CLASS. - - In these instructions, the word 'primal' refers to the graph you will get - if you don't use -d, and 'dual' refers to the dual of that graph (which - you get instead by using -d). - - The character # refers to a non-negative integer. - - We begin with a few switches available in multiple circumstances. - - -m# Specify a lower bound on the minimum degree. In the dual graph this - means a lower bound on the minimum face size. The default is -m3. - - -c# Specify a lower bound on the connectivity. The meaning in the dual - graph will be explained in each case. The default is -c3. - (-c4 has a slightly weaker meaning with -q, see below.) - - -x When used in combination with -c#, the connectivity must be exactly #, - rather than at least #. (Some exceptions are noted below.) - - Now we can explain the graph classes which can be produced by plantri. - - -b but not -p - Select eulerian triangulations, where "eulerian" means that every - vertex has even degree. -m is not available except for the default - -m4 (the minimum degree is always 4 anyway). - - -c3 (default) 3-connected eulerian plane triangulation. - The dual is a 3-connected bipartite cubic graph. - - -c4 4-connected eulerian plane triangulation. - The dual is a cyclically 4-connected bipartite cubic graph. - - -c3x The difference between -c3 and -c4, namely those 3-connected - eulerian plane triangulations which have a triangle that is - not a face. - - -p but not -b - Select general plane simple graphs. In the 3-connected case, these - are also called convex polytopes. Note that isomorphism is defined - with reference to the embedding on a sphere, which means that outputs - may be isomorphic as abstract graphs if the connectivity is less - than 3. - - -m1 The minimum degree is at least 1. - -m2 The minimum degree is at least 2. - -m3 (default) The minimum degree is a least 3. - -m4 The minimum degree is at least 4. - -m5 The minimum degree is at least 5 (and so exactly 5). - - -c4 The connectivity is at least 4. - -c3 (default) The connectivity is at least 3. - -c2 The connectivity is at least 2. - -c1 The connectivity is at least 1. - -c2x The difference between -c2 and -c3, namely connectivity exactly 2. - -c1x The difference between -c1 and -c2, namely connectivity exactly 1. - - If the -c switch is used but not the -m switch, the minimum degree is - set to the same value. For example, -c2 is the same as -c2m2. - - If the -m switch is used but not the -c switch, 3-connectivity is - assumed. This means that -m1 and -m2 are ineffective without using - -c1 or -c2 as well. - - In addition, two limits can be imposed: - - -e Specify bounds on the number of edges (which is equal to the - number of edges in the dual). The default is no bounds. - For n vertices, the number of edges can be from ceil(3n/2) - (2n for -m4, ceil(5n/2) for -m5) to 3n-6. - There are four possible forms: - -e# number of edges exactly # - -e:# number of edges at most # - -e#: number of edges at least # - -e#:# number of edges from # to # - Only the lower bound is efficiently implemented. Generally - speaking, it is more efficient to do a range of edge counts - at once rather than one edge count at a time. - - -f# Specify an upper bound on the size of a face (in the dual: an - upper bound on the maximum degree). The default is no bound. - For n vertices, the largest face size can be from 3 to n-1. - - -bp or -pb - Select general plane simple bipartite graphs. These are a subset - of the class generated by -p alone, namely those which are bipartite. - The minimum degree is always at most 3, so all the parameters - available with -p are available except -c4, -m4, -m5 and -f3. - - The duals are a subclass of plane eulerian graphs. - For -c3, the duals are the 3-connected plane eulerian graphs. - - -P# Select triangulations of a disk. These are embedded simple graphs - with a distinguished "outer" face. The outer face can be any size - (here called the disk size) but the other faces must be triangles. - - The argument to -P is the disk size. If no argument (or 0) is given, - all disk sizes are permitted. If all disk sizes are needed, it is a - lot more efficient to do them all at once rather than one at a time. - - Except for the outer face, all vertices must have degree at least 3. - On the outer face, vertices of degree 2 may be permitted, according - to the -m parameter. Also, the only 2-cuts which may exist are - chords of the outer face: they are permitted for -c2 but not for -c3. - Since a vertex of degree 2 on the outer face implies a chord, the - combination -m2c3 is the same as -m3c3. - - The useful combinations of -c, -m and -x are listed: - - -c3m3 (default) no chords, no vertices degree 2 - -c2 chords allowed, no vertices degree 2 - -c2x chords required, no vertices degree 2 - -c2m2 chords allowed, degree 2 allowed - -c2xm2 chords required, degree 2 allowed - - We have c2P = c3m3P + c2xP and c2m2P = c3m3P + c2xm2P. - - The output graphs are labelled in such a way that v-w is an - edge and the outer face is on the left when looking from v-w, - where v is the first vertex and w is the second vertex. - For dual output, the first vertex corresponds to the outer - face. The dual graph is a graph which has every vertex of - degree 3 except possibly the first vertex. - - When interpretting the output, remember that the outer face is - distinguished and that this is taken into account in determining - isomorphisms. It means, for example, that some of the outputs with - outer face of size 3 will be isomorphic as abstract graphs even in - the 3-connected case. - - -q Select simple quadrangulations. These are simple plane graphs for - which every face has length 4. The dual graphs are plane quartic - graphs. - - -x is not implemented. - The useful combinations of -c and -m are listed: - - -c3m3 (default) 3-connected - dual: 3-connected simple quartic graphs - -c2m2 arbitrary - dual: 4-edge-connected (maybe not simple) - quartic multigraphs - -c2 minimum degree 3 - dual: 4-edge-connected simple quartic graphs - -c4 3-connected, no non-facial 4-cycles - dual: 3-connected, 6-cyclically-edge-connected - (simple) quartic graphs - - -Q Select general quadrangulations, allowing multiple edges. - No connectivity or degree restrictions are currently available. - The dual graphs are general plane quartic graphs, allowing multiple - edges and loops. - - -A Select Appolonian networks. These are simple plane triangulations - that can be formed starting with K4 then repeatedly dividing a face - into three by addition of a new vertex. They all have minimum - degree and connectivity equal to 3. - - The dual graphs are cubic plane graphs which can be made from K4 - by repeatedly replacing a vertex by a triangle. - - If -b, -q, -Q, -p, -P and -A are absent, the graphs found are triangulations - only restricted by connectivity and minimum degree. In this case, - there is the possibility of connectivity lower than 3. - - The useful combinations of -c, -m, -x and -t are: - - -c3m3 (default) 3-connected plane triangulation. - The dual is a 3-connected plane cubic graph. - Both primal and dual graphs are simple. - - -m5 3-connected plane triangulation with minimum degree 5. - The dual is a 3-connected plane cubic graph with no faces - smaller than pentagons. Both primal and dual graphs are simple. - - -c5 5-connected plane triangulation (implies minimum degree 5). - The dual is a cyclically 5-connected plane cubic graph. - Both primal and dual graphs are simple. - - -m5c4 4-connected plane triangulation with minimum degree 5. The - The dual is a cyclically 4-connected plane cubic graph with - no faces smaller than pentagons. Both primal and dual graphs - are simple. - - -m5c3x 3-connected plane triangulation with minimum degree 5 - and at least one non-facial triangle. The dual is a - 3-connected plane cubic graph with no faces smaller than - pentagons but at least one cyclic 3-cut. Both primal and - dual graphs are simple. - - -m5c4x 4-connected plane triangulation with minimum degree 5 - and at least one separating 4-cycle. The dual is a - 4-connected plane cubic graph with no faces smaller than - pentagons but at least one cyclic 4-cut. Both primal and - dual graphs are simple. - - -m4 3-connected plane triangulation with minimum degree at least 4. - The dual is a 3-connected plane cubic graph with no triangles. - Both primal and dual graphs are simple. - - -c4 4-connected plane triangulation (implies minimum degree >= 4). - The dual is a cyclically 4-connected plane cubic graph. - Both primal and dual graphs are simple. - - -c4x, -c5x are not allowed (but see -m5c4x). - - -m4c3x 3-connected plane triangulation with minimum degree at - least 4 and at least one non-facial triangle. The dual is a - 3-connected plane cubic graph with no triangles but at least - one cyclic 3-cut. Both primal and dual graphs are simple. - - -c2 2-connected plane triangulation with minimum degree at least 3. - There may be parallel edges (but remember it is a triangulation - so there must be things between each pair of them). There are - no loops. The dual is a 2-connected simple plane cubic graph. - - -c2x Same as -c2 except that there must be at least one pair of - parallel edges. In the dual, at least one cutset of size 2. - - -m2c2 2-connected plane triangulation with minimum degree at least 2. - There can be parallel edges but no loops. The dual is a - 2-connected plane cubic graph which may have multiple edges - but has no loops. - - In the case of -c1, there is an extra switch -t which changes the - class. For a triangulation a "special configuration" consists of - two faces that consist of a double edge with a loop inside at one - end and a loop outside at the other end. In the dual cubic graph, - this corresponds to a double edge which does not bound a face - (so it has an edge pointing inside at one end and an edge pointing - outside at the other end). In all cases, special configurations - are allowed if -t is used and forbidden otherwise. - - In these descriptions loops and double edges are permitted except - as indicated. - - -c1 (same as -m3c1) Planar triangulation with minimum degree at - least 3 and no special configurations. The dual is a plane - cubic graph no non-facial 2-cycles. - - -c1t (same as -m3c1t) Arbitrary plane triangulation with minimum - degree at least 3. The dual is an arbitrary plane cubic graph. - - -m2c1 Planar triangulation with minimum degree at least 2 but no - special configurations. The dual is a plane cubic graph - with no loops or non-facial 2-cycles. - - -m2c1t Planar triangulation with minimum degree at least 2. - The dual is a plane cubic graph with no loops. - - -m1c1 Planar triangulation with no special configurations. - The dual is a plane cubic graph with no non-facial 2-cycles. - - -m1c1t Arbitrary plane triangulation. The dual is an arbitrary - plane cubic graph. - - We have c2 = c2x + c3, c1 = c1x + c2, and c1t = c1tx + c2. - Also m2c1 = m2c1x + m2c2 and m1c1 = m1c1x + m1c2. - Also m2c1t = m2c1tx + m2c2 and m1c1t = m1c1tx + m1c2. - Also m4 = m4c3x + c4, m5c4 = m5c4x + c5, and m5 = m5c4x + m5c3x + c5. - -MORE ON RES/MOD SPLITTING. - - The feature selected by the optional res/mod parameter to plantri is one - of its greatest strengths. The set of objects is divided into mod disjoint - classes and only the res-th class is generated. It is necessary that - 0 <= res <= mod-1. The splitting is designed so that the overhead is at - most 5 seconds per run for a 500MHz machine. Also, for problems where - there are very many objects altogether, the value of mod can be at least - as large as 10,000 and still have reasonable uniformity of class size. - - The definition of the classes obeys the normal laws of modulo arithmetic. - For example, class 1/5 is the union of 1/10 and 6/10 (since the numbers - equal to 1 modulo 5 are the numbers equal to 1 or 6 modulo 10). This - enables classes to be further split into smaller pieces if the need arises. - - To determine the actual cost of splitting, and the maximum number of - classes available, run the program plantri_s (known to the makefile). - For example: - % plantri_s -b 30 - 9030731 splitting cases at level=24; cpu=7.63 sec - This says that splitting into up to 9030731 cases is feasible (though the - splitting won't be very uniform if you use that many) and the cost of the - splitting is about 7.6 seconds for each run. (In this case, it means that - using 400 classes incurs a splitting penalty of only one percent.) - - Plugins can change the splitting level by defining splithint in the - expansion of PLUGIN_INIT. - - The switch -X increases the splitting level by 1 if possible, making the - splitting more uniform at the cost of more overhead. You can repeat it, - as in -XX. You must use the same number of Xs for each part. - -APPENDIX A. Definition of PLANAR CODE. - - PLANAR CODE is the default output format for plantri. The vertices of - the graph are numbered starting at 1. PLANAR CODE represents the graph - by a series of bytes, whose unsigned numerical values (0..255) are - significant. The first byte gives the number of vertices n. Then there - are n sections, where section v contains the neighbours of vertex v in - clockwise order followed by a zero byte. There is no end-of-line - character appended. - - For example, the graph of Figure 1 is represented by the following - byte values: - - 5 3 4 0 3 5 0 1 4 5 2 0 1 5 3 0 2 3 4 0 - - In case there are parallel edges, there might be more than one graph - whose PLANAR CODE is the same up to rotation of the neighbour lists. - To resolve this ambiguity, plantri makes the following convention: - for each vertex v except for the first vertex, if the least numbered - vertex that has v as a neighbour is w, then the first w in the section - for v represents the same edge as the first v in the section for w. - - In case of all the graph classes generated by plantri that have no - multiple loops, and also for all classes of triangulations, it can be - proved that for every v > 1 we have w < v and the embedded graph is - uniquely reconstructible from the code. - - In addition to the encodings of graphs, a PLANAR CODE file by default - begins with the 15 characters >>planar_code<< without end-of-line - characters. - -APPENDIX B. Definition of EDGE CODE. - - EDGE CODE is an alternative to PLANAR CODE that has the advantage of - being uniquely decodable for all plane graphs (even with multiple loops). - The undirected edges are numbered 0,1,... consecutively but in - no particular order, and for each vertex a list of the incident - edge numbers in clockwise order is given. Note that a loop appears - twice in such a list, and in general each edge number appears - exactly twice altogether. - - The code consists of a header and a body. The header has one of - two forms: - 1. A single byte of value 1-255. In this case, the value of the - byte is the size of the body in bytes. All edge numbers in the - body will be encoded using L=1 bytes. - 2. The byte 0, a byte (K<<4)+L (where 1<=K,L<=15), and a bigendian - unsigned number S stored in K bytes. In this case, S is the size - of the body in bytes and L is the number of bytes used for edge - numbers in the body. The size of the header is 1+1+K bytes. - - The body has a section for each vertex. In each section, the edge - numbers for the incident edges are given in clockwise order, using - an L-byte bigendian integer for each. Each vertex section except - the last is followed by a single byte of value 255. (Note that this - implies L is large enough that the largest edge number has first - byte value at most 254.) - - In plantri, the only possibility for the second header type is K=2, L=1. - - In addition to the encodings of graphs, an EDGE CODE file by default - begins with the 13 characters >>edge_code<< without end-of-line - characters. - -APPENDIX C. Definition of GRAPH6 and SPARSE6. - - All numbers in this description are in decimal unless obviously in - binary. GRAPH6 and SPARSE6 are text formats, and a file containing - them is a text file. - - Apart from the header, there is one object per line. Apart from the - header and the end-of-line characters, all bytes have a value in the - range 63-126 (which are all printable ASCII characters). - - BIT VECTORS: - - A bit vector x of length k can be represented as follows. - Example: 1000101100011100 - - (1) Pad on the right with 0 to make the length a multiple of 6. - Example: 100010110001110000 - - (2) Split into groups of 6 bits each. - Example: 100010 110001 110000 - - (3) Add 63 to each group, considering them as bigendian binary numbers. - Example: 97 112 111 - - These values are then stored one per byte. - So, the number of bytes required is ceiling(k/6). - - Let R(x) denote this representation of x as a string of bytes. - - SMALL NONNEGATIVE INTEGERS: - - Let n be an integer in the range 0-262143 (262143 = 2^18-1). - - If 0 <= n <= 62, define N(n) to be the single byte n+63. - If n >= 63, define N(n) to be the four bytes 126 R(x), where - x is the bigendian 18-bit binary form of n. - - Examples: N(30) = 93 - N(12345) = N(000011 000000 111001) = 126 69 63 120 - - - GRAPH6 format: - - Suppose G has n vertices. Write the upper triangle of the adjacency - matrix of G as a bit vector x of length n(n-1)/2, using the ordering - (0,1),(0,2),(1,2),(0,3),(1,3),(2,3),...,(n-1,n). - - Then the graph is represented as N(n) R(x). - - Example: Suppose n=5 and G has edges 0-2, 0-4, 1-3 and 3-4. - - x = 0 10 010 1001 - - Then N(n) = 68 and R(x) = R(010010 100100) = 81 99. - So, the graph is 68 81 99. - - Note that GRAPH6 format cannot represent loops or parallel edges. - - SPARSE6 format: - - The encoded graph consists of: - (1) The character ':'. (This is present to distinguish - the code from GRAPH6 format.) - (2) The number of vertices. - (3) A list of edges. - (4) end-of-line - - Loops and multiple edges are supported, but not directed edges. - - Number of vertices n: Represented as N(n) like in GRAPH6 format. - - List of edges: - - Let k be the number of bits needed to represent n-1 in binary. - The remaining bytes encode a sequence R(z) where - z = b[0] x[0] b[1] x[1] b[2] x[2] ... b[m] x[m] ... - - Each b[i] occupies 1 bit, and each x[i] occupies k bits. - Padding at the end is chosen so that the decoding algorithm below - does not imply any spurious edges. - - The vertices of the graph are 0..n-1. - The edges encoded by this sequence are determined thus: - - v = 0 - for i from 0 to m do - if b[i] = 1 then v = v+1 endif; - if x[i] > v then v = x[i] else output {x[i],v} endif - endfor - - Example: :Fa@x^ - ':' indicates sparse6 format. - Subtract 63 from the other bytes and write them in binary, six bits each. - 000111 100010 000001 111001 011111 - The first byte is not 63, so it is n. n=7 - n-1 needs 3 bits (k=3). Write the other bits in groups of 1 and k: - 1 000 1 000 0 001 1 110 0 101 1 111 - This is the b/x sequence 1,0 1,0 0,1 1,6 0,5 1,7. - The 1,7 at the end is just padding. - The remaining pairs give the edges 0-1 1-2 5-6. - - -APPENDIX D. Writing Plug-ins for plantri. - - plantri has a facility for making certain compile-time changes to its - behaviour. This requires some amount of knowledge of how the program - works, and here we will give a little of that. A typical use for - a plug-in is to filter the output graphs before they are written. - This is a good idea if you are only wanting some subset of the graphs, - because plantri is so fast that writing graphs out and reading them - into another program takes about as long as generating them. - - Vertices in plantri are numbered starting at 0. There are global - variables nv and ne which contain the number of vertices and the - number of DIRECTED edges (which is twice the number of edges). - - In the case of disk triangulations, there are some occasions when - one vertex number is unused. In this case, the global int variable - missing_vertex indicates what is missing. If nothing is missing, - missing_vertex < 0. For example, if nv=7 and missing_vertex=2, the - vertices are actually numbered 0,1,3,4,5,6,7. - - The graph is held as a collection of directed edges (type EDGE). - These edges are structures referenced by pointers. They have these - fields, amongst others: - - int start; the vertex at the start of the edge - int end; the vertex at the end of the edge - EDGE *invers; the directed edge which is the reverse of this one - EDGE *next; the next edge in clockwise order around vertex start - EDGE *prev; the previous edge in clockwise order around vertex start - - To find the edges, there is an array firstedge[0..], type EDGE*. - The value of firstedge[i] is a pointer to one of the edges starting - at vertex v. - - For example, to "look at" all the neighbours of vertex v we can do: - - EDGE *e,*elast; - - e = elast = firstedge[v]; - do - { - look at e->end; - e = e->next; - } while (e != elast); - - Another example is the tracing of a face. Suppose we have an edge e and - we want to "look at" all the edges bounding the face on the right of e. - - elast = e; - do - { - look at e; - e = e->invers->prev; - } while (e != elast); - - Use e = e->invers->next instead if you are interested in the face on - the left of e. - - Another useful global array is degree[0..], which contains the - degrees of the vertices. Another way to "look at" all the neighbours - of vertex v is this: - - for (count = degree[v], e = firstedge[v]; --count >= 0; e = e->next) - { - look at e->end - } - - - To write a plug-in, you need to define some things in a separate source - file (let's call it plugin.c), and make the name of that source file - available when compiling plantri.c. For example, on most Unix systems: - cc -o plantri_plugin -O4 '-DPLUGIN="plugin.c"' plantri.c - All the quotes of both types are required. - - This process causes the text of plugin.c to be read into the text of - plantri.c, so everything defined in each file is available in both. - The work of the plug-in is achieved by defining macros. Here we list - the macros that might be defined, and their meanings. If you don't - want these functions, just don't define the macros. - - FILTER This is the name of a procedure that is called for each - isomorphism type of graph that would normally be output (except - that in the case of -d it is the original graph before taking - the dual). The calling sequence is like this: - int FILTER(int nbtot, int nbop, int doflip) - The procedure must return an int value. If the value 0 is - returned, the graph is not written. Otherwise it is written. - - The meanings of the parameters: - nbtot = total number of automorphisms - nbop = number of canonical labellings which are O-P. - If there are O-R automorphisms, nbop=nbtot/2, while if - there are none nbop=0 or nbop=nbtot. - doflip = 0 if there is an orientation-reversing automorphism, - otherwise 1 - - nbtot, nbop, doflip are only guaranteed correct if -G or -o is - given. In that case the full automorphism group is available; - contact the authors for details. - - Without -G and -o, doflip=0 and the other parameters are undefined. - - These rules mean that doflip+1 is the number of graphs which are - to be written (except for the embedding-insensitive formats graph6 - and sparse6, for which only one will be written). If you are using - FILTER to count outputs with a particular property, count each - graph with a weight of doflip+1. - - This procedure can be used to write the graph in another format. - The normal output file (an open text file) is outfile, except - if -u is given, in which case you will have to open a file - yourself or use stdout. - - SUMMARY This is called at the end of the computation before the final - summary statistics are produced by plantri. Type: - void SUMMARY(void) - Its main use is to write information gathered by FILTER and other - plug-in components. If you don't want the normal summary as well, - set the global variable dosummary to 0 before returning. - - Look in plantri.c to see how statistics are collected and written. - All statistics should be written to the file msgfile. - - PLUGIN_INIT This is called at the start of execution, after the - command-line switches have been decoded but before any graphs - are generated. You can use it to perform tasks such as: - (a) Test if the switches are valid for this plug-in. - (b) Set switch values to appropriate default values. - (c) Initialize data-structures used by this plug-in. - - PLUGIN_SWITCHES This can be defined to add extra switches. The mechanism - for detecting switches, and their values, can be best seen by - examining plantri.c. Here are two simple cases: - (a) Add a boolean switch -z: - #define PLUGIN_SWITCHES else if (arg[j] == 'z') zswitch = TRUE; - (b) Add a switch -z that takes an integer value: - #define PLUGIN_SWITCHES else if (arg[j] == 'z') \ - zvalue = getswitchvalue(arg,&j); - In each case you have to define and initialize the new variables. - You can do that at the top level in plugin.c: - (a) static int zswitch = FALSE; - (b) static int zvalue = -1; - Checking that zvalue is valid, or giving it a default value if it - is not specified (i.e. is still -1), can be done using PLUGIN_INIT. - - If you change the switches, you should also redefine the macro - SWITCHES that appears in the first line of plantri.c. It is - only used in error messages. - - PRE_FILTER_* These are the most difficult macros to use, as considerable - knowledge of the internals of the program is required. plantri - operates by starting with the smallest graphs in the required - class, then expanding them by a few vertices at a time until the - output size is reached. The exact method for expanding a graph - depends on the graph class. The value of PRE_FILTER_* is an - expression that is evaluated for each intermediate graph computed - during the generation process that is smaller (or less constructed - in some other sense) than the output size. If the value of the - expression is 0, that intermediate graph is not expanded (so none - of its descendants appear in the output). If the value is not 0, - expansion proceeds as normal. - - The actual macros available are - PRE_FILTER_SIMPLE, PRE_FILTER_MIN4, PRE_FILTER_BIP, - PRE_FILTER_POLY, PRE_FILTER_DOUBLE, PRE_FILTER_ORDLOOP, - PRE_FILTER_SPECIALLOOP, PRE_FILTER_QUAD, PRE_FILTER_MIN5. - - A few more complex macros are available, but describing them would - require too much detail about plantri internals. - - Some examples of plug-ins are distributed with plantri: - mdcount.c (makes plantri_mdcount) - count graphs by minimum degree - degseq.c (makes plantri_deg) - counts graphs by degree sequence - nft.c (makes plantri_nft) - counts graphs by non-facial triangles - maxdeg.c (makes plantri_md) - imposes a bound on the maximum degree - allowed_deg.c (makes plantri_ad) - specify which degrees are permitted - faceorbits.c (makes plantri_fo) - count plane embeddings with - distinguished outer face - -APPENDIX E. Graph Counts. - - In this section we list some counts of the graph classes that can be - generated using plantri. If you compute any additional numbers in - any of these classes, please send them to us for inclusion. - - The column headings in these tables are: - - nv = number of vertices (or faces in the dual) - ne = number of edges (same in the dual) - nf = number of faces (or vertices in the dual) - - all = count of isomorphism classes - O-P = count of orientation-preserving isomorphism classes. - - ---------------------------------------------------------------- - - 3-connected plane triangulations. - - nv ne nf all O-P - - 4 6 4 | 1 1 - 5 9 6 | 1 1 - 6 12 8 | 2 2 - 7 15 10 | 5 6 - 8 18 12 | 14 17 - 9 21 14 | 50 73 - 10 24 16 | 233 389 - 11 27 18 | 1249 2274 - 12 30 20 | 7595 14502 - 13 33 22 | 49566 97033 - 14 36 24 | 339722 672781 - 15 39 26 | 2406841 4792530 - 16 42 28 | 17490241 34911786 - 17 45 30 | 129664753 259106122 - 18 48 32 | 977526957 1954315346 - 19 51 34 | 7475907149 14949368524 - 20 54 36 | 57896349553 115784496932 - 21 57 38 | 453382272049 906736988527 - 22 60 40 | 3585853662949 7171613842488 - 23 63 42 | 28615703421545 57231089062625 - - ---------------------------------------------------------------- - - 3-connected plane triangulations with minimum degree at least 4, - (plantri -m4), and 4-connected plane triangulations (plantri -c4). - - m4 c4 - - nv ne nf all O-P all O-P - - 6 12 8 | 1 1 | 1 1 - 7 15 10 | 1 1 | 1 1 - 8 18 12 | 2 2 | 2 2 - 9 21 14 | 5 5 | 4 4 - 10 24 16 | 12 14 | 10 12 - 11 27 18 | 34 45 | 25 32 - 12 30 20 | 130 194 | 87 128 - 13 33 22 | 525 891 | 313 519 - 14 36 24 | 2472 4499 | 1357 2430 - 15 39 26 | 12400 23603 | 6244 11765 - 16 42 28 | 65619 127887 | 30926 59915 - 17 45 30 | 357504 705770 | 158428 311744 - 18 48 32 | 1992985 3959653 | 836749 1659633 - 19 51 34 | 11284042 22494163 | 4504607 8971845 - 20 54 36 | 64719885 129227103 | 24649284 49195863 - 21 57 38 | 375126827 749646288 | 136610879 272940855 - 22 60 40 | 2194439398 4387116659 | 765598927 1530417953 - 23 63 42 | 12941995397 25878895923 | 4332047595 8661936137 - 24 66 44 | 76890024027 153765144588 | 24724362117 49442678322 - 25 69 46 | 459873914230 919704309272 | 142205424580 284393946501 - 26 72 48 | 2767364341936 5534600480206 | 823687567019 1647327455726 - 27 75 50 | 16747182732792 | 4801749063379 - - Note: An earlier version of this table gave a different value for - the first count on the nv=23 row. That was due to a clerical error - and not to a program bug. - - ---------------------------------------------------------------- - - plane triangulations without 3-connectivity requirement. - A "special configuration" is two faces formed by a pair of parallel - edges with a loop inside one end and a loop outside the other end. - conn = a lower bound on the connectivity - delta = a lower bound on the minimum degree - - conn=2 delta=3 (plantri -c2) - conn=1 delta=3 and no special configuration (plantri -c1) - conn=1 delta=3 (plantri -c1t). - - conn=2 delta=2 (plantri -m2c2) - conn=1 delta=2 and no special configuration (plantri -m2c1) - conn=1 delta=2 (plantri -m2c1t). - - conn=1 delta=1 and no special configuration (plantri -m1c1) - conn=1 delta=1 (plantri -m1c1t). - - c2 - - nv all O-P - - 4 | 1 1 - 5 | 1 1 - 6 | 3 3 - 7 | 8 9 - 8 | 32 37 - 9 | 131 183 - 10 | 723 1156 - 11 | 4360 7713 - 12 | 29632 55436 - 13 | 213168 412193 - 14 | 1606633 3158392 - 15 | 12473723 24736138 - 16 | 99141919 197448348 - 17 | 802392930 1601481238 - 18 | 6593377305 13173471151 - 19 | 54883010885 109712447949 - 20 | 462038444588 923858502128 - 21 | 3928893849911 7856893675780 - - - c1 c1t - - nv all O-P all O-P - - 4 | 1 1 | 1 1 - 5 | 1 1 | 1 1 - 6 | 3 3 | 3 3 - 7 | 9 10 | 9 10 - 8 | 37 42 | 38 43 - 9 | 172 230 | 178 236 - 10 | 993 1523 | 1041 1577 - 11 | 6308 10737 | 6652 11188 - 12 | 44145 80319 | 46738 84194 - 13 | 327051 620134 | 347050 653271 - 14 | 2530761 4913112 | 2691419 5198809 - 15 | 20179785 39705720 | 21509955 42184083 - 16 | 164672106 326420796 | 175969274 348088277 - 17 | 1368137926 2723097802 | 1465921468 2913967487 - 18 | 11536196188 23012381739 | 12395111621 24706425434 - 19 | 98494508358 196713776094 | 106126249031 211856940558 - 20 | 850073936750 1698875856077 | 918520748281 1835160731391 - 21 | 7406965136219 14808015829668 | 8025676381104 16042357404748 - - - m2c2 - - nv all O-P - - 3 | 1 1 - 4 | 2 2 - 5 | 4 4 - 6 | 14 14 - 7 | 54 66 - 8 | 291 409 - 9 | 1873 3078 - 10 | 14468 26044 - 11 | 123730 235054 - 12 | 1139820 2223598 - 13 | 11012340 21770878 - 14 | 110159674 219136678 - 15 | 1131227001 2256904588 - 16 | 11864336461 23702178103 - 17 | 126639415621 253151362072 - 18 | 1372246820875 2743873167600 - 19 | 15065904311738 30128766834832 - - m2c1 m2c1t - - nv all O-P all O-P - - 3 | 1 1 1 1 - 4 | 2 2 2 2 - 5 | 5 5 5 5 - 6 | 19 19 20 20 - 7 | 94 112 100 118 - 8 | 581 802 634 862 - 9 | 4297 6864 4738 7451 - 10 | 36388 63985 40412 70132 - 11 | 337952 630270 376812 696162 - 12 | 3349489 6455215 3749104 7180627 - 13 | 34738800 68154023 39044043 76306202 - 14 | 372459154 737599845 420546653 830919184 - 15 | 4096051566 8151111206 4647701181 9236590422 - 16 | 45968549270 91704568206 52427373251 104510610443 - 17 | 524625804817 1047919071939 601467756683 1200901913663 - 18 | 6073627332266 12139545642813 6999845695102 13987563528656 - - m1c1 m1c1t - - nv all O-P all O-P - - 3 | 2 2 2 2 - 4 | 5 5 6 6 - 5 | 21 22 25 26 - 6 | 125 154 156 191 - 7 | 997 1502 1272 1904 - 8 | 9906 17017 12924 22078 - 9 | 115036 213553 152706 282388 - 10 | 1478952 2855841 1997650 3848001 - 11 | 20342243 40036445 27960796 54953996 - 12 | 293294847 582364274 410416310 814302292 - 13 | 4378778380 8729474470 6239790783 12434664412 - 14 | 67181358581 134172729792 97510238990 194705958478 - 15 | 1053929763051 2106555903824 1558296770458 3114359909400 - 16 | 16846298319763 25375343842763 50734620915690 - - ---------------------------------------------------------------- - - 3-connected plane Eulerian triangulations (plantri -b), - and 4-connected plane Eulerian triangulations (plantri -bc4). - - b bc4 - - nv ne nf all O-P all O-P - - 6 12 8 | 1 1 | 1 1 - 7 15 10 | 0 0 | 0 0 - 8 18 12 | 1 1 | 1 1 - 9 21 14 | 1 1 | 0 0 - 10 24 16 | 2 2 | 2 2 - 11 27 18 | 2 2 | 1 1 - 12 30 20 | 8 9 | 5 6 - 13 33 22 | 8 11 | 3 3 - 14 36 24 | 32 41 | 18 22 - 15 39 26 | 57 89 | 19 25 - 16 42 28 | 185 296 | 79 112 - 17 45 30 | 466 829 | 134 214 - 18 48 32 | 1543 2772 | 501 817 - 19 51 34 | 4583 8746 | 1147 2058 - 20 54 36 | 15374 29461 | 3976 7188 - 21 57 38 | 50116 98342 | 11055 21036 - 22 60 40 | 171168 336881 | 37231 71185 - 23 63 42 | 582603 1156559 | 114560 224103 - 24 66 44 | 2024119 4024297 | 384053 753561 - 25 69 46 | 7057472 14075250 | 1244056 2464355 - 26 72 48 | 24873248 49638364 | 4193857 8321649 - 27 75 50 | 88111772 176037177 | 13977946 27841706 - 28 78 52 | 314301078 628107157 | 47522279 94737950 - 29 81 54 | 1126716000 2252541666 | 161222224 321889797 - 30 84 56 | 4060375677 8118442511 | 553033544 1104620101 - 31 87 58 | 14697571234 29390845869 | 1899744032 3796766424 - 32 90 60 | 53432834170 106854715443 | 6571595339 13136256710 - 33 93 62 | 195015189626 390009407529 | 22793047258 45572625554 - 34 96 64 | 714404259151 1428755867040 | 79449718217 158865787212 - 35 99 66 | 2626130395699 5252157292165 | 277760027418 555452882736 - 36 102 68 | 9685071313079 | 974836112457 - - ---------------------------------------------------------------- - - Convex polytopes (3-connected plane simple graphs, plantri -p), - and convex polytopes with minimum degree at least 4 (plantri -pm4). - - p pm4 - - nv all O-P all O-P - - 4 1 1 | - 5 2 2 | - 6 7 8 | 1 1 - 7 34 45 | 1 1 - 8 257 419 | 4 4 - 9 2606 4798 | 14 16 - 10 32300 62754 | 67 99 - 11 440564 872411 | 428 720 - 12 6384634 12728018 | 3515 6531 - 13 96262938 192324654 | 31763 61677 - 14 1496225352 2991463239 | 307543 607787 - 15 23833988129 47663036427 | 3064701 6101800 - 16 387591510244 775158142233 | 31199068 62288750 - 17 6415851530241 12831576165782 | 322264655 644101914 - 18 107854282197058 | 3369911732 6738127018 - 19 | 35611596455 71216447022 - 20 | 379881408164 759735751770 - 21 | 4086847012014 8173585336482 - - ---------------------------------------------------------------- - - Triangulations of a disk: 3-connected (plantri -P), or exactly - 2-connected but without vertices of degree 2 (plantri -Pc2x), - or exactly 2-connected with vertices of degree 2 on the outer - face permitted (plantri -Pc2m2). - - P - - nv all O-P - - 4 1 1 - 5 2 2 - 6 7 8 - 7 27 37 - 8 132 213 - 9 773 1386 - 10 5017 9524 - 11 34861 68057 - 12 253676 501858 - 13 1903584 3788747 - 14 14616442 29170667 - 15 114254053 228295618 - 16 906266345 1811802818 - 17 7277665889 14552804492 - 18 59066524810 118124257451 - 19 483864411124 967698049455 - 20 3996427278475 7992746427963 - 21 33250623548406 66500865364037 - - Pc2x Pc2xm2 - - nv all O-P all O-P - - 3 | 1 1 - 4 | 1 1 - 5 | 2 2 - 6 1 1 | 9 12 - 7 4 5 | 36 56 - 8 27 42 | 196 341 - 9 163 289 | 1160 2168 - 10 1131 2130 | 7616 14732 - 11 8030 15631 | 52605 103619 - 12 59412 117319 | 379339 753336 - 13 448361 891666 | 2814161 5610649 - 14 3447550 6877352 | 21363658 42666989 - 15 26887369 53713758 | 165164873 330125084 - 16 212338376 424461698 | 1296637273 2592566706 - 17 1695218973 3389687444 | 10312933521 20623423424 - 18 13666153626 27329645755 | 82959235392 165909929181 - 19 111136594337 222263795690 | 674004472100 1347979078869 - 20 910959545329 1821885598755 | 5524400982592 11048696658907 - 21 7520705838434 15041292477945 | 45637448298918 91274524809807 - - ---------------------------------------------------------------- - - 3-connected plane triangulations with minimum degree 5 (plantri -m5), - and 3-connected plane graphs (convex polytopes) with minimum degree 5 - (plantri -pm5). - - triangulations polytopes - - nv ne nf all O-P all O-P - - 12 30 20 | 1 1 | 1 1 - 13 33 22 | 0 0 | 0 0 - 14 36 24 | 1 1 | 1 1 - 15 39 26 | 1 1 | 1 1 - 16 42 28 | 3 4 | 5 6 - 17 45 30 | 4 4 | 8 8 - 18 48 32 | 12 17 | 30 46 - 19 51 34 | 23 33 | 85 135 - 20 54 36 | 73 117 | 392 686 - 21 57 38 | 192 331 | 1587 2961 - 22 60 40 | 651 1180 | 7657 14744 - 23 63 42 | 2070 3899 | 36291 71207 - 24 66 44 | 7290 14052 | 180444 357308 - 25 69 46 | 25381 49667 | 898310 1787611 - 26 72 48 | 91441 180502 | 4532719 9042238 - 27 75 50 | 329824 654674 | 22949165 45839601 - 28 78 52 | 1204737 2398527 | 116805726 233457359 - 29 81 54 | 4412031 8800984 | 596228948 1192066180 - 30 84 56 | 16248772 32447008 | 3052696452 6104366484 - 31 87 58 | 59995535 119883207 | 15667197926 31331752928 - 32 90 60 | 222231424 444226539 | 80591725752 161176530535 - 33 93 62 | 825028656 1649550311 | 415411427833 830804928594 - 34 96 64 | 3069993552 6138874486 | 2145396827091 4290746578254 - 35 99 66 | 11446245342 22890091062 | 11100060860777 22199999305869 - 36 102 68 | 42758608761 85511947468 | - 37 105 70 | 160012226334 320013030067 | - 38 108 72 | 599822851579 1199620598580 | - 39 111 74 | 2252137171764 4504219709753 | - 40 114 76 | 8469193859271 16938267502048 | - - A previous version of this table had the nv=29 value 8800984 incorrect - for unknown reasons. It does seem that the program always got the - right answer. - - ---------------------------------------------------------------- - - 3-connected plane quadrangulations (plantri -q). - - quadrangulations - - nv ne nf all O-P - - 8 12 6 | 1 1 - 9 14 7 | 0 0 - 10 16 8 | 1 1 - 11 18 9 | 1 1 - 12 20 10 | 3 4 - 13 22 11 | 3 3 - 14 24 12 | 11 15 - 15 26 13 | 18 25 - 16 28 14 | 58 92 - 17 30 15 | 139 234 - 18 32 16 | 451 803 - 19 34 17 | 1326 2469 - 20 36 18 | 4461 8512 - 21 38 19 | 14554 28290 - 22 40 20 | 49957 98148 - 23 42 21 | 171159 338673 - 24 44 22 | 598102 1188338 - 25 46 23 | 2098675 4180854 - 26 48 24 | 7437910 14840031 - 27 50 25 | 26490072 52904562 - 28 52 26 | 94944685 189724510 - 29 54 27 | 341867921 683384218 - 30 56 28 | 1236864842 2472961423 - 31 58 29 | 4493270976 8984888982 - 32 60 30 | 16387852863 32772085447 - 33 62 31 | 59985464681 119963084542 - 34 64 32 | 220320405895 440623586740 - 35 66 33 | 811796327750 1623555117611 - 36 68 34 | 3000183106119 6000283550482 - - (In a previous version of this table, the two values for nv=31 were - interchanged. Thanks to Hugo Pfoertner for noticing.) - - ---------------------------------------------------------------- - - General quadrangulations (plantri -Q) - - nv ne nf all O-P - - 3 2 1 | 1 1 - 4 4 2 | 3 3 - 5 6 3 | 7 7 - 6 8 4 | 30 33 - 7 10 5 | 124 156 - 8 12 6 | 733 1070 - 9 14 7 | 4586 7515 - 10 16 8 | 33373 59151 - 11 18 9 | 259434 483925 - 12 20 10 | 2152298 4136964 - 13 22 11 | 18615182 36416865 - 14 24 12 | 166544071 329048627 - 15 26 13 | 1528659536 3037029030 - 16 28 14 | 14328433429 28553451498 - 17 30 15 | 136649176084 272766018806 - 18 32 16 | 1322594487342 2642420298576 - 19 34 17 | 12965736092988 25916954091582 - 20 36 18 | 128543259338048 257009789443925 - - ---------------------------------------------------------------- - - Appolonian networks. - - nv ne nf all O-P - - 4 6 4 | 1 1 - 5 9 6 | 1 1 - 6 12 8 | 1 1 - 7 15 10 | 3 4 - 8 18 12 | 7 10 - 9 21 14 | 24 40 - 10 24 16 | 93 171 - 11 27 18 | 434 831 - 12 30 20 | 2110 4147 - 13 33 22 | 11002 21822 - 14 36 24 | 56713 116062 - 15 39 26 | 321776 642600 - 16 42 28 | 1792133 3582322 - 17 45 30 | 10131027 20256885 - 18 48 32 | 57949430 115888201 - 19 51 34 | 334970205 669911568 - 20 54 36 | 1953890318 3907720521 - 21 57 38 | 11489753730 22979343010 - 22 60 40 | 68054102361 136107859377 - 23 63 42 | 405715557048 811430160282 - - ---------------------------------------------------------------- - -APPENDIX F. Version History - -The original edition of plantri, which performed only a few of the -functions of the current edition, was released in June 1996. Here -we will list the changes made in the functionality of recent editions -only. Internal changes are listed in plantri.c. - -Version 3.0: - Released on April 25, 2000. - -Version 3.1: - Released on July 3, 2000. - - It was discovered by Thom Sulanke that the code for simple - triangulations stopped working correctly at 26 or more vertices. - The bug does not affect any of the calculation sizes listed in - Appendix E. We believe that the only possible way of encountering - the bug with the distributed software was to use the maxdeg or - allowed_deg programs for 26 or more vertices. Correct operation - with -m4, -c4, -b and the min5 plugin was not affected. - - Version 3.1 corrects the bug without otherwise changing program - behaviour. Many thanks to Thom for his assistance. - -Version 4.0: - Released on April 20, 2001. - - Added -q for 3-connected quadrangulations. - Added -pc1 and -pc2 for general plane graphs. - Added -m5 and variants. The plug-in min5.c is no longer required. - sparse6 output now represents loops only once. - -Version 4.1: - Released on November 30, 2001. - - Added -qc2, -qc4, -qm2c2 for types of quadrangulation. - -Version 4.3: - Released on August 5, 2007. - - Added -V : write only those with non-trivial groups - Added -E : write output in edge code - Added -bp : general bipartite graphs - -p can now make graphs of 2 or 3 vertices - -Version 4.4: - Released on May 2, 2009. - - Fixed -pc1x and -pc2x - Fixed incorrect connectivity computation in -p and -pb, - only known problems were with -c1x, -c2x and statistics - reported by -v - -Version 4.5: - Released on September 5, 2011. - - Also apply FAST_FILTER_* to starting graphs (all uses need checking - against the code as more than one filter might need defining) - -Version 4.6: - Minor internal changes only. - -Version 4.7: - Released on March 8, 2014. - - Added Appolonian graphs. - -Version 5.0: - Released on October 2, 2016. - - Added 4-connected polytopes (-pc4). - -Version 5.2: - Released on February 28, 2018. - - Added -E for text edgecode output. - Fixed case -m4c3x which didn't work as advertised. - Fixed the group of the gyro (triangulation with 3 vertices and one loop). - Readjusted all splitting levels. - -Version 5.3: - Released on May 17, 2022. - - An error in splitting for cases -q and -pb could cause some graphs - to be output multiple times in version 5.2 (but not earlier). - Also removed erroneous interpretation of CLOCKS_PER_SEC. - -Version 5.4: - Released on March 10, 2023. - - -Q was added for general quadrangulations. - -Version 5.5: - Released on May 17, 2024. - - Fixed splitting for trivial sizes of -p (2 or 3 vertices). - - ---------------------------------------------------------------- - -APPENDIX G. Copyright and license - -This is the copyright statement for plantri and associated utilities. - -Copyright is jointly held by the authors - Gunnar Brinkmann, University of Gent, gunnar.brinkmann@ugent.be - Brendan McKay, Australian National University, brendan.mcKay@anu.edu.au - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this software except in compliance with the License. -A copy of the License is included in the package and you can also -view it at - - https://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. diff --git a/apn/lean/docs/polymake/LICENSE b/apn/lean/docs/polymake/LICENSE deleted file mode 100644 index 6eda76f4..00000000 --- a/apn/lean/docs/polymake/LICENSE +++ /dev/null @@ -1,361 +0,0 @@ -************************************************************************ -* The GNU General Public License cited below applies to the * -* entire polymake code written in whatever programming language. * -* * -* There are, however, parts of third-party software included in this * -* distribution with the solely aim to make the installation process * -* easier. Most are protected by GPL too, but for some packages * -* other open source licenses apply. In any case, free non-commercial * -* use and redistribution are allowed without restrictions. * -* * -* Please refer to the appropriate copyright notices in the * -* external/* subdirectories for details. * -* * -* Please note also, that for the sake of reducing the distribution * -* size, the bundled packages do not contain tutorials, examples, * -* documentation, or other components not used by polymake. You may * -* obtain them, if needed, directly from the original websites. * -************************************************************************ - - - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 59 Temple Place - Suite 330 - Boston, MA 02111-1307, USA. - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) 19yy - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; see the file COPYING. If not, write to - the Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) 19yy name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. diff --git a/apn/lean/docs/polymake/polymake.md b/apn/lean/docs/polymake/polymake.md deleted file mode 100644 index 1070ea7e..00000000 --- a/apn/lean/docs/polymake/polymake.md +++ /dev/null @@ -1,1872 +0,0 @@ - - -# polymake 4.6 usage - -Start the interactive shell with `polymake`. Run a script non-interactively with `polymake --script ` (see the Scripting section at the end). The shell language is polymake/Perl. - -# Using Perl within polymake - -The language that the interactive version of `polymake` speaks is a dialect of Perl that we refer to as `polymake`/Perl. See [www.perl.org](http://www.perl.org) for comprehensive Perl information. Note also that the ordinary Perl manual pages are particularly useful, especially the perlintro man page which is also available on [perldoc](http://perldoc.perl.org/perlintro.html). This short section here cannot be a replacement for a thorough introduction to this language, but we want to focus on a few key points that are relevant to `polymake`. - -### Standard data structures - -The Perl programming language originally provides three different data structures, scalars(`$`), arrays(`@`), and hashes(`%`). The user always has to specify the type of a variable using the appropriate symbol `$`, `@`, or `%`. If you forget to do so, you will receive the following error message: - - > i=5; - polymake: ERROR: Unquoted string "i" may clash with future reserved word. - - - - - -Here are some simple commands illustrating how to use the different data structures: -##### Scalars - - -```perl -$i=5; -$j=6; -$sum=$i+$j; print $sum; -``` -Output: -``` -11 -``` - - -##### Arrays - - - - -```perl -@array=("a","b","c"); print scalar(@array); -push(@array,"d"); print "@array"; -$first_entry=$array[0]; print $first_entry; -print join("\n",@array); -@array2=(3,1,4,2); -print sort(@array2); -``` -Output: -``` -3a b c daa -b -c -d1234 -``` - - -##### Hashes - - - - -```perl -%hash=(); -$hash{"zero"}=0; -$hash{"four"}=4; -print keys %hash; -print join(", ",keys %hash); -print join(", ",values %hash); -%hash=("one",1,"two",2); -%hash=("one"=>1,"two"=>2); -``` -Output: -``` -fourzerofour, zero4, 0 -``` - - -### `polymake`-Perl - -In addition to the three standard data structures, the enriched version of `Perl` used in `polymake` also provides special data structures for dealing with more complicated concepts. For an introduction to the polymake object model see [here](properties.ipynb#Objects). - -`polymake`'s object hierarchy is completely reflected on the Perl side. Let us create a small polytope as an example object. - - - - -```perl -$p = new Polytope(POINTS=>[[1,0,1],[1,0,-1],[1,1,0],[1,-1,0]]); -``` - - -Note that the `Perl`-type of the variable `$p` is `Scalar`, as the variable is internally treated as a reference to a `C++`-object. The true nature of the object becomes visible if it is printed: - - - - -```perl -print $p; -``` -Output: -``` -Polymake::polytope::Polytope__Rational=ARRAY(0x55c8aa54c778) -``` - -In this case it is a `polymake` object from the application `polytope`, and it happens to be of type `Polytope`. Technically, `$p` is a reference to an array (but it should be never treated as an array unless you are deliberately trying to crash `polymake`). If you want less technical information on the type of your object, use this: - -```perl -print $p->type->full_name; -``` -Output: -``` -Polytope -``` - - -#### "Small objects": Data structures inherited from C++ - -You can use objects that are inherited from the `C++`-side of `polymake` in the interactive shell. A complete list of so-called "small objects" can be found in the [online documentation](https://polymake.org/doku.php/documentation/latest/common#property_types). -Here is a selection of three different structures that facilitate everyday work with `polymake`: -##### Arrays - -The small object `Array` can be initialized in different ways and with different template parameters: - - - - -```perl -@array=("a","b","c"); -$arr1=new Array(\@array); print $arr1; -$arr2=new Array([3,2,5]); print $arr2; -$arr3=new Array(0,1,2,3); print $arr3; -$arr4=new Array(0..4); print $arr4; -$arr5=new Array($arr4); print $arr5; -``` -Output: -``` -a b c3 2 50 1 2 30 1 2 3 40 1 2 3 4 -``` - - -You have random access: - - - - -```perl -$arr5->[0] = 100; -print $arr5; -``` -Output: -``` -100 1 2 3 4 -``` - - It is also possible to convert the `C++`-object `Array` into a `Perl`-array by writing - - - - -```perl -@arr4=@{$arr4}; print $arr2; -``` -Output: -``` -3 2 5 -``` - - - or simply - - - - -```perl -@arr4=@$arr4; -``` - - -##### Sets - -On `C++`-side sets are stored in a balanced binary search (AVL) tree. For more information see the [PTL-documentation](https://polymake.org/release_docs/master/PTL/classpm_1_1Set.html). In many cases, the small objects can be converted into `Perl`-types in the expected way: - - - - -```perl -$set=new Set(3,2,5); print $set; -print $set->size; -@array_from_set=@$set; -``` -Output: -``` -{2 3 5}3 -``` - - -##### Matrices - -Here is a simple way to initialize a matrix: - - - - -```perl -$mat=new Matrix([[2,1,4,0,0],[3,1,5,2,1],[1,0,4,0,6]]); -print $mat; -``` -Output: -``` -2 1 4 0 0 -3 1 5 2 1 -1 0 4 0 6 -``` - - - You could also define it by passing a reference to an (`Perl`-)array of `Vectors`. The single entries are interpreted as different rows: - - - - -```perl -$row1=new Vector([2,1,4,0,0]); -$row2=new Vector([3,1,5,2,1]); -$row3=new Vector([1,0,4,0,6]); -@matrix_rows=($row1,$row2,$row3); -$matrix_from_array=new Matrix(\@matrix_rows); -``` - - - You can change a single entry of a matrix in the following way (if it is not already assigned to an immutable property like `VERTICES`!): - - - - -```perl -$mat->row(1)->[1]=7; -print $mat->row(1)->[1], "\n"; -print $mat, "\n"; -$mat->elem(1,2)=8; -print $mat; -``` -Output: -``` -7 -2 1 4 0 0 -3 7 5 2 1 -1 0 4 0 6 - -2 1 4 0 0 -3 7 8 2 1 -1 0 4 0 6 -``` - - - A unit matrix of a certain dimension can be defined via the user-function `unit_matrix(.)`: - - - - -```perl -$unit_mat=4*unit_matrix(3); -print $unit_mat; -``` -Output: -``` -(3) (0 4) -(3) (1 4) -(3) (2 4) -``` - - - The reason for the "strange output" is the implementation as *sparse matrix*: - - - - -```perl -print ref($unit_mat); -``` -Output: -``` -Polymake::common::SparseMatrix_A_Rational_I_NonSymmetric_Z -``` - - -However, some functions cannot deal with this special type of matrix. In this case it is necessary to transform the sparse matrix into a dense matrix first via: - - - - -```perl -$dense=new Matrix($unit_mat);print $dense; -``` -Output: -``` -4 0 0 -0 4 0 -0 0 4 -``` - - - or just - - - - -```perl -$dense2=dense($unit_mat);print $dense2; -``` -Output: -``` -4 0 0 -0 4 0 -0 0 4 -``` - - - You can also work with matrices that have different types of coordinates like `Rational`, `Float`, or `Int`: - - - - -```perl -$m_rat=new Matrix(3/5*unit_matrix(5)); print $m_rat, "\n"; -$m2=$mat/$m_rat; print $m2, "\n"; -$m_int=new Matrix(unit_matrix(5)); print $m_int, "\n"; -``` -Output: -``` -3/5 0 0 0 0 -0 3/5 0 0 0 -0 0 3/5 0 0 -0 0 0 3/5 0 -0 0 0 0 3/5 - -2 1 4 0 0 -3 7 8 2 1 -1 0 4 0 6 -3/5 0 0 0 0 -0 3/5 0 0 0 -0 0 3/5 0 0 -0 0 0 3/5 0 -0 0 0 0 3/5 - -1 0 0 0 0 -0 1 0 0 0 -0 0 1 0 0 -0 0 0 1 0 -0 0 0 0 1 -``` - -Sometimes there is incompatible types: -```perl -> $m3=$m_rat/$m_int; -``` -``` -C++/perl Interface module compilation failed; most likely due to a type mismatch. -Set the variable $Polymake::User::Verbose::cpp to a positive value and repeat for more details. -``` - -The error message indicates that you need to convert the integer matrix to a rational matrix first: - -```perl -$m3=$m_rat/(convert_to($m_int)); print $m3; -``` -Output: -``` -3/5 0 0 0 0 -0 3/5 0 0 0 -0 0 3/5 0 0 -0 0 0 3/5 0 -0 0 0 0 3/5 -1 0 0 0 0 -0 1 0 0 0 -0 0 1 0 0 -0 0 0 1 0 -0 0 0 0 1 -``` - - - By "/" you can add rows to a matrix, whereas "|" adds columns. By the way, this also works for `Vector`. - - - - -```perl -$z_vec=zero_vector($m_int->rows); -$extended_matrix=($z_vec|$m_int); print $extended_matrix; -``` -Output: -``` -0 1 0 0 0 0 -0 0 1 0 0 0 -0 0 0 1 0 0 -0 0 0 0 1 0 -0 0 0 0 0 1 -``` - - -It is also possible to nest template parameters in any way you like, e.g. - - - - -```perl -$set=new Set(3,2,5); -$template_Ex=new Array>((new Set(5,2,6)),$set); print $template_Ex; print ref($template_Ex); -``` -Output: -``` -{2 5 6} -{2 3 5} -Polymake::common::Array__Set__Int -``` - - -However, if you use a template combination, you have never used before, it may take some time until you see the result. This is due to the fact that `polymake` compiles your new combination *on the fly*. But this is only a one-time effect, and next time you use this combination it will work without delay. - -#### "Big Objects": Objects with properties - -A big object is an instance of a data type which represents a mathematical concept with clear semantics. They may have template parameters. - - - - -```perl -$p=new Polytope(POINTS=>cube(4)->VERTICES); -$lp=new LinearProgram(LINEAR_OBJECTIVE=>[0,1,1,1,1]); -``` - - -Big objects have properties which come with a type, which is either built-in or a small object type or a big object type, and which can be accessed using the `-``>` operator. - - - - -```perl -# access the property named `LP`: -$p->LP=$lp; -# properties can have properties themselves. -print $p->LP->MAXIMAL_VALUE; -``` -Output: -``` -4 -``` - - - -Scalar properties can be used in arithmetic expressions right away. - - - - -```perl -$i = ($p->N_FACETS * $p->N_FACETS) * 15; -``` - - - - -```perl -print $i; -``` -Output: -``` -960 -``` - -Check out the tutorial on [properties](properties.ipynb) to learn more about the way properties are used and computed. - -### A small example script... - -...to demonstrate the usage of `polymake`/Perl. You can download the matrix file [here](https://polymake.org/lib/exe/fetch.php/points.demo). - - - -```perl -### load matrix from file -open(INPUT, "< demo/Workshop2011/points.demo"); -$matrix=new Matrix(); -close(INPUT); -print $matrix; - - -### create a polytope from the matrix -$p=new Polytope(POINTS=>$matrix); -print $p->FACETS; -print $p->DIM; -print $p->VERTEX_SIZES; - - -### print "simple" vertices -for(my $i=0;$iVERTEX_SIZES});$i++){ - if($p->VERTEX_SIZES->[$i]==$p->DIM){ - print $i.": ".$p->VERTICES->row($i)."\n"; - } -} - - -### put their indices in a set -$s=new Set(); -for(my $i=0;$iVERTEX_SIZES});$i++){ - if($p->VERTEX_SIZES->[$i]==$p->DIM){ - $s+=$i; - } -} - - -### iterate the set in two different ways -foreach(@{$s}){ - print $p->VERTICES->row($_)."\n"; -} -foreach my $index(@{$s}){ - print $p->VERTICES->row($index)."\n"; -} - - -### create a minor of the vertices matrix that only contains the simple ones -$special_points=$p->VERTICES->minor($s,All); print $special_points; -``` -Output: -``` --1 -``` - -### Writing scripts - -Comprehensive information on how to use scripts within `polymake` can be found [here](https://polymake.org/doku.php/user_guide/howto/scripting). - -# Tutorial on Polytopes - -A *polytope* is the convex hull of finitely many points in some Euclidean space. Equivalently, a polytope is the bounded intersection of finitely many affine halfspaces. `polymake` can deal with polytopes in both representations and provides numerous tools for analysis. - - -This tutorial first shows basic ways of defining a polytope from scratch. For larger input (e.g. from a file generated by some other program) have a look at our HowTo on [loading data](data.ipynb) in `polymake`. - - -The second part demonstrates some of the tool `polymake` provides for handling polytopes by examining a small example. For a complete list of properties of polytopes and functions that `polymake` provides, see the [polytope documentation](https://polymake.org/doku.php/documentation/latest/polytope). - -## Constructing a polytope from scratch - - -### V-Description - -To define a polytope as the convex hull of finitely many points, you can pass a matrix of coordinates to the constructor. Since `polymake` uses [homogeneous coordinates](coordinates.ipynb), you need to set the additional coordinate x0 to 1. - - -```perl -$p = new Polytope(POINTS=>[[1,-1,-1],[1,1,-1],[1,-1,1],[1,1,1],[1,0,0]]); -``` - - -The `POINTS` can be any set of coordinates, they are not required to be irredundant nor vertices of their convex hull. To compute the actual vertices of our polytope, we do this: - - - - -```perl -print $p->VERTICES; -``` -Output: -``` -1 -1 -1 -1 1 -1 -1 -1 1 -1 1 1 -``` - -You can also add a lineality space via the input property `INPUT_LINEALITY`. - - - - -```perl -$p2 = new Polytope(POINTS=>[[1,-1,-1],[1,1,-1],[1,-1,1],[1,1,1],[1,0,0]],INPUT_LINEALITY=>[[0,1,0]]); -``` - - -To take a look at what that thing looks like, you can use the `VISUAL` method: - - - - -```perl -$p2->VISUAL; -``` - - -See [here](visual_tutorial.ipynb#application-polytope) for details on visualizing polytopes. - - If you are sure that all the points really are *extreme points* (vertices) and your description of the lineality space is complete, you can define the polytope via the properties `VERTICES` and `LINEALITY_SPACE` instead of `POINTS` and `INPUT_LINEALITY`. This way, you can avoid unnecessary redundancy checks. - - - - The input properties `POINTS` / `INPUT_LINEALITY` may not be mixed with the properties `VERTICES` / `LINEALITY_SPACE`. Furthermore, the `LINEALITY_SPACE` **must be specified** as soon as the property `VERTICES` is used: - - - - -```perl -$p3 = new Polytope(VERTICES=>[[1,-1,-1],[1,1,-1],[1,-1,1],[1,1,1]], LINEALITY_SPACE=>[]); -``` - - -### H-Description - -It is also possible to define a polytope as an intersection of finitely many halfspaces, i.e., a matrix of inequalities. - - - -An inequality a0 + a1 x1 + ... + ad xd >= 0 is encoded as a row vector (a0,a1,...,ad), see also [Coordinates for Polyhedra](coordinates.ipynb). Here is an example: - - - - -```perl -$p4 = new Polytope(INEQUALITIES=>[[1,1,0],[1,0,1],[1,-1,0],[1,0,-1],[17,1,1]]); -``` - - -To display the inequalities in a nice way, use the `print_constraints` method. - - - - -```perl -print_constraints($p4->INEQUALITIES); -``` -Output: -``` -0: x1 >= -1 -1: x2 >= -1 -2: -x1 >= -1 -3: -x2 >= -1 -4: x1 + x2 >= -17 -5: 0 >= -1 -``` - -The last inequality means 17+x1+x2 >= 0, hence it does not represent a facet of the polytope. If you want to take a look at the acutal facets, do this: - - - - -```perl -print $p4->FACETS; -``` -Output: -``` -1 1 0 -1 0 1 -1 -1 0 -1 0 -1 -``` - - -If your polytope lies in an affine subspace then you can specify its equations via the input property `EQUATIONS`. - - - - - - -```perl -$p5 = new Polytope(INEQUALITIES=>[[1,1,0,0],[1,0,1,0],[1,-1,0,0],[1,0,-1,0]],EQUATIONS=>[[0,0,0,1],[0,0,0,2]]); -``` - - -Again, if you are sure that all your inequalities are facets, you can use the properties `FACETS` and `AFFINE_HULL` instead. Note that this pair of properties is dual to the pair `VERTICES` / `LINEALITY_SPACE` described above. - - -## Convex Hull Computations - -Of course, `polymake` can convert the V-description of a polytope to its H-description and vice versa. In fact, this is done automatically whenever you ask for a suitable property. - -For instance, continuing with the example above, the following triggers a dual convex hull computation. Note that this particular command does not compute any output. - -```perl -$p5->VERTICES; -``` - -Printing the vertices later does *not* result in a recomputation. Known properties are stored. - -```perl -print $p5->VERTICES; -``` -Output: -``` -1 1 -1 0 -1 1 1 0 -1 -1 1 0 -1 -1 -1 0 -``` - -Depending on the individual configuration polymake chooses one of the several convex hull computing algorithms that have a `polymake` interface. Available algorithms are double description ([cdd](http://www.ifor.math.ethz.ch/~fukuda/cdd_home/cdd.html) of [ppl](http://bugseng.com/products/ppl)), reverse search ([lrs](http://cgm.cs.mcgill.ca/~avis/C/lrs.html)), and beneath beyond (internal). It is also possible to specify explicitly which method to use by using the `prefer_now` command. Here we show a primal convex hull computaton, i.e., from V- to H-description, with lrs. - -```perl -prefer_now "lrs"; -$p = new Polytope(POINTS=>[[1,1],[1,0]]); -print $p->FACETS; -``` -Output: -``` -1 -1 -0 1 -``` - -Use `prefer` instead of `prefer_now` if you want to make this permanent. - -## A Neighborly Cubical Polytope - -`polymake` provides a variety of standard polytope constructions and transformations. This example construction introduces some of them. Check out the [documentation](https://polymake.org/doku.php/documentation/latest/polytope) for a comprehensive list. - -The goal is to construct a 4-dimensional cubical polytope which has the same graph as the 5-dimensional cube. It is an example of a *neighborly cubical* polytope as constructed in - - -* Joswig & Ziegler: Neighborly cubical polytopes. Discrete Comput. Geom. 24 (2000), no. 2-3, 325--344, [DOI 10.1007/s004540010039](http://www.springerlink.com/content/m73pqv6kr80rw4b1/) - -This is the entire construction in a few lines of `polymake` code: - - - - -```perl -$c1 = cube(2); -$c2 = cube(2,2); -$p1x2 = product($c1,$c2); -$p2x1 = product($c2,$c1); -$nc = conv($p1x2,$p2x1); -``` - - - -Let us examine more closely what this is about. First we constructed a square `$c1` via calling the function `cube`. The only parameter `2` is the dimension of the cube to be constructed. It is not obvious how the coordinates are chosen; so let us check. - - - - -```perl -print $c1->VERTICES; -``` -Output: -``` -1 -1 -1 -1 1 -1 -1 -1 1 -1 1 1 -``` - - -The four vertices are listed line by line in homogeneous coordinates, where the homogenizing coordinate is the leading one. As shown the vertices correspond to the four choices of `+/-1` in two positions. So the area of this square equals four, which is verified as follows: - - - - -```perl -print $c1->VOLUME; -``` -Output: -``` -4 -``` - - -Here the volume is the Euclidean volume of the ambient space. Hence the volume of a polytope which is not full-dimensional is always zero. - - - -The second polytope `$c2` constructed is also a square. However, the optional second parameter says that `+/-2`-coordinates are to be used rather than `+/-1` as in the default case. The optional parameter is also allowed to be `0`. In this case a cube with `0/1`-coordinates is returned. You can access the documentation of functions by typing their name in the `polymake` shell and then hitting F1. - - - -The third command constructs the polytope `$p1x2` as the cartesian product of the two squares. Clearly, this is a four-dimensional polytope which is combinatorially (even affinely) equivalent to a cube, but not congruent. This is easy to verify: - - - - -```perl -print isomorphic($p1x2,cube(4)); -``` -Output: -``` -true -``` - -```perl -print congruent($p1x2,cube(4)); -``` -Output: -``` -0 -``` - - -Both return values are boolean, represented by the numbers `1` and `0`, respectively. This questions are decided via a reduction to a graph isomorphism problem which in turn is solved via `polymake`'s interface to `nauty`. - - - -The polytope `$p2x1` does not differ that much from the previous. In fact, the construction is twice the same, except for the ordering of the factors in the call of the function `product`. Let us compare the first vertices of the two products. One can see how the coordinates are induced by the ordering of the factors. - - - - -```perl -print $p1x2->VERTICES->[0]; -``` -Output: -``` -1 1 -1 2 2 -``` - -```perl -print $p2x1->VERTICES->[0]; -``` -Output: -``` -1 2 -2 1 1 -``` - - -In fact, one of these two products is obtained from the other by exchanging coordinate directions. Thats is to say, they are congruent but distinct as subsets of Euclidean 4-space. This is why taking their joint convex hull yields something interesting. Let us explore what kind of polytope we got. - - - - -```perl -print $nc->SIMPLE, " ", $nc->SIMPLICIAL; -``` -Output: -``` -false false -``` - - -This says the polytope is neither simple nor simplicial. A good idea then is to look at the f-vector. Beware, however, this usually requires to build the entire face lattice of the polytope, which is extremely costly. Therefore this is computationally infeasible for most high-dimensional polytopes. - - - - -```perl -print $nc->F_VECTOR; -``` -Output: -``` -32 80 72 24 -``` - - -This is a first hint that our initial claim is indeed valid. The polytope constructed has 32 vertices and 80 = 32*5/2 edges, as many as the 5-dimensional cube: - - - - -```perl -print cube(5)->F_VECTOR; -``` -Output: -``` -32 80 80 40 10 -``` - - -What is left is to check whether the vertex-edge graphs of the two polytopes actually are the same, and if all proper faces are combinatorially equivalent to cubes. - - - - -```perl -print isomorphic($nc->GRAPH->ADJACENCY,cube(5)->GRAPH->ADJACENCY); -``` -Output: -``` -true -``` - -```perl -print $nc->CUBICAL; -``` -Output: -``` -true -``` - -See the [tutorial on graphs](apps_graph.ipynb) for more on that subject. - -# Objects, Properties and Rules - -### Objects -In polymake, there is two kinds of objects. A *Big Object* models a complex mathematical concept, like a Polytope or a SimplicialComplex, while a *small object* is an instance of one of the many data types commonly used in computer science, like Integers, Matrices, Sets or Maps. A big object consists of a collection of other objects (big or small) describing it, called *properties*, and functions to compute more properties from the ones already known, called *production rules*. - -To get a more detailed explanation of the `polymake` object model and properties, check out the [scripting guide](https://polymake.org/doku.php/user_guide/howto/scripting#most_important_interfaces). - -You can save polymake objects to disc, as explained [here](data.ipynb). - -### Properties - -Each (big) object has a list of properties of various types. When an object is 'born' it comes with an initial list of properties, and all other properties will be derived from those. Let's look at example from the `polytope` application. The following creates a 3-dimensional cube: - -```perl -$c=cube(3); -``` - -To find out what the initial set of properties is, use the `list_properties` method. It returns an array of strings. The extra code is just there to print this list nicely. - -```perl -print join(", ", $c->list_properties); -``` -Output: -``` -CONE_AMBIENT_DIM, CONE_DIM, FACETS, AFFINE_HULL, VERTICES_IN_FACETS, BOUNDED -``` - -To find out the type of the object `$c`, enter - -```perl -print $c->type->full_name; -``` -Output: -``` -Polytope -``` - - -To see what a property contains, use the `->` syntax: - - - - -```perl -print $c->FACETS; -``` -Output: -``` -1 1 0 0 -1 -1 0 0 -1 0 1 0 -1 0 -1 0 -1 0 0 1 -1 0 0 -1 -``` - - - 1 1 0 0 - 1 -1 0 0 - 1 0 1 0 - 1 0 -1 0 - 1 0 0 1 - 1 0 0 -1 - - -You can also get the content of all properties using the `properties` method: - - - - -```perl -$c->properties; -``` -Output: -``` -name: c -type: Polytope -description: cube of dimension 3 - - -AFFINE_HULL - - -BOUNDED -true - -CONE_AMBIENT_DIM -4 - -CONE_DIM -4 - -FACETS -1 1 0 0 -1 -1 0 0 -1 0 1 0 -1 0 -1 0 -1 0 0 1 -1 0 0 -1 - - -VERTICES_IN_FACETS -{0 2 4 6} -{1 3 5 7} -{0 1 4 5} -{2 3 6 7} -{0 1 2 3} -{4 5 6 7} -``` - -### Production Rules - -The object is changed if we ask for a property which has not been computed before. - -```perl -print $c->VERTICES; -``` -Output: -``` -1 -1 -1 -1 -1 1 -1 -1 -1 -1 1 -1 -1 1 1 -1 -1 -1 -1 1 -1 1 -1 1 -1 -1 1 1 -1 1 1 1 -``` - -```perl -print join(", ", $c->list_properties); -``` -Output: -``` -CONE_AMBIENT_DIM, CONE_DIM, FACETS, AFFINE_HULL, VERTICES_IN_FACETS, BOUNDED, FEASIBLE, POINTED, N_VERTICES, N_FACETS, VERTICES, LINEALITY_SPACE -``` - - -The property `VERTICES` was added, but a few others were computed on the way, too. `polymake` applied a sequence of *production rules* that add new properties to the object that can be computed from the properties the object already posesses. - -What properties *can* be computed for a given object depends on the set of rules defined for it. Here is a short sequence of commands which lets you find out. - - - - -```perl -$t=$c->type; -print join(", ", sorted_uniq(sort { $a cmp $b } map { keys %{$_->properties} } $t, @{$t->super})); -``` -Output: -``` -AFFINE_HULL, BALANCE, BALANCED, BOUNDARY_LATTICE_POINTS, BOUNDED, CANONICAL, CD_INDEX_COEFFICIENTS, CENTERED, CENTERED_ZONOTOPE, CENTRALLY_SYMMETRIC, CENTROID, CHIROTOPE, CIRCUITS, COCIRCUITS, COCIRCUIT_EQUATIONS, COCUBICAL, COCUBICALITY, COMBINATORIAL_DIM, COMPLEXITY, COMPRESSED, CONE_AMBIENT_DIM, CONE_DIM, CS_PERMUTATION, CUBICAL, CUBICALITY, CUBICAL_H_VECTOR, DEGREE_ONE_GENERATORS, DUAL_BOUNDED_H_VECTOR, DUAL_GRAPH, DUAL_H_VECTOR, EDGE_ORIENTABLE, EDGE_ORIENTATION, EHRHART_POLYNOMIAL, EHRHART_QUASI_POLYNOMIAL, EQUATIONS, EXCESS_RAY_DEGREE, EXCESS_VERTEX_DEGREE, F2_VECTOR, FACETS, FACETS_THRU_INPUT_RAYS, FACETS_THRU_POINTS, FACETS_THRU_RAYS, FACETS_THRU_VERTICES, FACET_SIZES, FACET_VERTEX_LATTICE_DISTANCES, FACET_VOLUMES, FACET_WIDTH, FACET_WIDTHS, FACE_SIMPLICITY, FAR_FACE, FAR_HYPERPLANE, FATNESS, FEASIBLE, FLAG_VECTOR, FOLDABLE_COCIRCUIT_EQUATIONS, FOLDABLE_MAX_SIGNATURE_UPPER_BOUND, FTR_CYCLIC_NORMAL, FTV_CYCLIC_NORMAL, FULL_DIM, F_VECTOR, FacetPerm, FacetPerm.pure, GALE_TRANSFORM, GALE_VERTICES, GORENSTEIN, GORENSTEIN_CONE, GORENSTEIN_INDEX, GORENSTEIN_VECTOR, GRAPH, GROEBNER_BASIS, GROUP, G_VECTOR, HASSE_DIAGRAM, HILBERT_BASIS_GENERATORS, HILBERT_SERIES, HOMOGENEOUS, H_STAR_VECTOR, H_VECTOR, INEQUALITIES, INEQUALITIES_THRU_RAYS, INEQUALITIES_THRU_VERTICES, INPUT_LINEALITY, INPUT_RAYS, INPUT_RAYS_IN_FACETS, INPUT_RAY_LABELS, INTERIOR_LATTICE_POINTS, INTERIOR_RIDGE_SIMPLICES, LATTICE, LATTICE_BASIS, LATTICE_CODEGREE, LATTICE_DEGREE, LATTICE_EMPTY, LATTICE_POINTS_GENERAT -... [output truncated] -``` - - - -Instead of showing the (lengthy) enumeration have a look at the [documentation](https://polymake.org/doku.php/documentation/latest/polytope) for a complete list of properties known for objects of the application `polytope`. - - -#### Schedules - -You may wonder what sequence of rules led to the computation of a property you request. There usually are several mathematical ways to compute a property. `polymake` uses a nice scheduling algorithm to find the most efficient procedure, and you can look at what it returns. - -Suppose we want to see which sequence of rules leads to the computation of the F_VECTOR. - - - - -```perl -$schedule=$c->get_schedule("F_VECTOR"); -print join("\n", $schedule->list); -``` -Output: -``` -LINEALITY_DIM : LINEALITY_SPACE -COMBINATORIAL_DIM : CONE_DIM, LINEALITY_DIM -precondition : COMBINATORIAL_DIM ( F_VECTOR : N_FACETS, N_RAYS, COMBINATORIAL_DIM ) -F_VECTOR : N_FACETS, N_RAYS, COMBINATORIAL_DIM -``` - -So if you ask for the f-vector, `polymake` will first compute the dimension of the lineality space from the basis of the lineality space, then compute the combinatorial dimension from the lineality and cone dimensions, and then compute the f-vector from the number of facets, number of rays, and combinatorial dimension of the polytope. Applying the schedule to the object yields the same as asking for the property right away: - -```perl -$schedule->apply($c); -print join(", ", $c->list_properties); -``` -Output: -``` -CONE_AMBIENT_DIM, CONE_DIM, FACETS, AFFINE_HULL, VERTICES_IN_FACETS, BOUNDED, FEASIBLE, POINTED, N_VERTICES, N_FACETS, VERTICES, LINEALITY_SPACE, LINEALITY_DIM, COMBINATORIAL_DIM, F_VECTOR -``` - -As you can see, the things `polymake` needed to compute in order to get to the f-vector are stored in the object as well, so you don't have to recompute them later. - -If you're interested, read more about rule scheduling in the [scripting guide](https://polymake.org/doku.php/user_guide/howto/scripting#rule_planning) and the article on [writing rules yourself](https://polymake.org/doku.php/user_guide/extend/rulefiles). - -# Tutorial for Lattice Polytopes - -This page gives a small introduction to lattice polytopes in `polymake`, some useful external software, and usage hints for it. For a list of methods and properties applicable to lattice polytopes see [here](https://polymake.org/doku.php/user_guide/lattice_polytopes_doc). For an introduction to the `polymake` package see [here](https://polymake.org/doku.php/user_guide/start). - - -`polymake` always assumes that the lattice used to define a lattice polytope is the standard lattice Zd. Some rules also require that the polytope is full dimensional. There are user functions that transform a polytope sitting in some affine subspace of Rd into a full dimensional polytope, either in the induced lattice or the lattice spanned by the vertices, see below. - - - -## Dependence on other Software - -For some computations `polymake` has no built-in commands and passes the computation to external software. Currently, polymake has an interface to the following packages that compute various properties of lattice polytopes. - -* [libnormaliz](http://www.math.uos.de/normaliz/) by Winfried Bruns and Bogdan Ichim, bundled with polymake - -* [4ti2](http://www.4ti2.de/) by the 4ti2 team - -* [LattE macchiato](http://www.math.ucdavis.edu/~mkoeppe/latte/) by Matthias Köppe, building on `LattE` by Jesus de Loera et. al. - -* ([barvinok](http://freshmeat.net/projects/barvinok) by Sven Verdoolaege) - -Unless you want to deal with Hilbert bases of cones you don't need them. If you do, either the bundled extension `libnormaliz` or the external package `4ti2` suffices to do most computations with lattice polytopes. Computation of Gröbner bases currently requires `4ti2`. `LattE` only counts lattice points in a polytope and computes its Ehrhart polynomial, but may be faster on that than any other methods implemented. `barvinok` can be used to compute the number of lattice points and the h-polynomial. Access to barvinok is realized via an extension which has to be downloaded separately. - - For some of the commands in this tutorial you will need at least one of `bundled:libnormaliz` enabled or `4ti2` installed on your machine. We'll remind you at the relevant places. - - - -## Lattice Points in Rational Polytopes - -We start by creating a rational polytope using one of `polymake`'s standard polytope constructions. We choose the 3-dimensional cube with coordinates +1 and -1. So we start `polymake` at the command line and assign a cube to the variable $p. - - -```perl -$p=cube(3); -``` - - -Suppose we want to know how many lattice points this cube contains. The answer is of course already known, as the cube has one relative interior integral point per non-empty face. So we expect to get the answer 27. - - - - -```perl -print $p->N_LATTICE_POINTS; -``` -Output: -``` -27 -``` - -To satisfy this request, `polymake` computes all properties necessary to call an external program that provides the number of lattice points. In this case, `polymake` has passed the request to `lattE`, which is shown by the credit message that appears before the answer. By default, credits for external software are shown when an external package is used for the first time. You can change this behavior using the variable `$Verbose::credits`. If you don't have a version of `LattE`, or if you have set different preferences, then `polymake` may choose one of the other programs. So the credit statement depends on your configuration. - - -We can of course also ask `polymake` to compute the integral points for us. For our next computations we are only interested in the integral points in the interior of the cube, so we ask for - - - - -```perl -print $p->INTERIOR_LATTICE_POINTS; -``` -Output: -``` -1 0 0 0 -``` - -Internally, `polymake` computes the intersection of the polytope with the integer lattice, and then checks which of the points lies on a facet of $p. By default, `polymake` uses a project-and-lift algorithms to enumerate the lattice points. Note that our call to `LattE` above has only computed the number of integral points (which is done with an improved version of Barvinok's algorithm), so `polymake` really has to compute something here. If we had asked for `INTERIOR_LATTICE_POINTS` first, then `N_LATTICE_POINTS` would just have counted the rows of a matrix, which would have been much faster. So computation time can depend on the history. - -You can also ask for the HILBERT_BASIS, though in the case of a cube the result is not so exciting: - - - - -```perl -print $p->HILBERT_BASIS; -``` -Output: -``` -1 -1 -1 -1 -1 -1 -1 0 -1 -1 -1 1 -1 -1 0 -1 -1 -1 0 0 -1 -1 0 1 -1 -1 1 -1 -1 -1 1 0 -1 -1 1 1 -1 0 -1 -1 -1 0 -1 0 -1 0 -1 1 -1 0 0 -1 -1 0 0 0 -1 0 0 1 -1 0 1 -1 -1 0 1 0 -1 0 1 1 -1 1 -1 -1 -1 1 -1 0 -1 1 -1 1 -1 1 0 -1 -1 1 0 0 -1 1 0 1 -1 1 1 -1 -1 1 1 0 -1 1 1 1 -``` - -`polymake` has no native method to compute a Hilbert basis, so it has passed the computation to `4ti2`. The choice may vary, depending on what is installed on your computer (and configured for `polymake`). You can influence the choice with the appropriate `prefer` statement. - -Note that so far these commands also work for rational polytopes. - -## Lattice Polytopes - -Now we want to do some computations that don't make sense for polytopes that have non-integral vertex coordinates. We can let `polymake` check that our cube is indeed a polytope with integral vertices. - - - - -```perl -print $p->LATTICE; -``` -Output: -``` -true -``` - -A particularly interesting class of lattice polytopes is that of reflexive polytopes. A polytope is *reflexive* if its polar is agein alattice polytope. This implies in particular that the origin is the unique interior lattice point in the polytope. So, as we have seen above, our cube is a candidate. But this is not sufficient, so we have to do further checks. - - -Reflexivity is a property that is not defined for polytopes with non-integral vertices. So if we ask for it in `polymake`, then `polymake` checks that the entered polytope is indeed a lattice polytope (i.e. it is **bounded** and has **integral vertices**). In that case the object will automatically get the specialization `Polytope::Lattice`. - -```perl -print $p->REFLEXIVE; -``` -Output: -``` -true -``` - -Lattice polytopes can be used to define toric varieties with an ample line bundle, and many properties of the variety are reflected by the polytope. here is an example: The toric variety defined by our cube is *smooth*, i.e. it is one of the *smooth toric Fano varieties*. In `polymake`, we can just ask for this property in the following way. - -```perl -print $p->SMOOTH; -``` -Output: -``` -true -``` - - -The number of integral points in the k-th dilate of a polytope is given by a polynomial of degree d in k. This is the famous *Ehrhart Theorem*. In `polymake` you can obtain the coefficients of this polynomial (starting with the constant coefficient). - - - - -```perl -print $p->EHRHART_POLYNOMIAL; -``` -Output: -``` -8*x^3 + 12*x^2 + 6*x + 1 -``` - -`polymake` has passed this request to `LattE` or `normaliz`, but as we have used these programs already the credit message is suppressed (but if you save the cube to a file, then you will find it in there). Some coefficients of this polynomial have a geometric interpretation. E.g., the highest coefficient is the Euclidean volume of the polytope. - - - - -```perl -print $p->VOLUME; -``` -Output: -``` -8 -``` - -By a theorem of Stanley, the generating function for the number of lattice points can be written as the quotient of a polynomial h(t) by (1-t)d+1, and this polynomial has non-negative integral coefficients. - - - - -```perl -print $p->H_STAR_VECTOR; -``` -Output: -``` -1 23 23 1 -``` - -```perl -print $p->LATTICE_DEGREE; -``` -Output: -``` -3 -``` - -```perl -print $p->LATTICE_CODEGREE; -``` -Output: -``` -1 -``` - -In our case the coefficient vector is symmetric, as the polytope is reflexive. The *co-degree* of the polytope is d+1 minus the degree of the h-polynomial. It is the smallest factor by which we have to dilate the polytope to obtain an interior integral point. In our case, this is 1, as the cube already has an integral point. - - -We can obtain the volume of our polytope also from the `H_STAR_VECTOR`: Summing up the coefficients give the *lattice volume* of the polytope, which is d! times its Euclidean volume. - - - - -```perl -print $p->LATTICE_VOLUME; -``` -Output: -``` -48 -``` - - -Let us look at a different example: - - - - -```perl -$q=new Polytope(INEQUALITIES=>[[5,-4,0,1],[-3,0,-4,1],[-2,1,0,0],[-4,4,4,-1],[0,0,1,0],[8,0,0,-1],[1,0,-1,0],[3,-1,0,0]]); -``` - - -This actually defines a lattice polytope, which we can see from the list of vertices: - - - - -```perl -print $q->VERTICES; -``` -Output: -``` -1 3 1 7 -1 2 0 3 -1 3 0 7 -1 2 1 7 -1 2 0 4 -1 3 1 8 -1 3 0 8 -1 2 1 8 -``` - -`polymake` provides basically three methods for convex hull conversion, double description, reverse search, and beneath beyond. The first two are provided by the packages `cdd` and `lrs`, the last in internal. By default, `cdd` is chosen, and that is what was used above (they are bundled with `polymake`, you don't have to install them). A polytope Q is *normal* if every lattice point in the k-th dilate of Q is the sum of k lattice points in Q. You can check this property via - - - - -```perl -print $q->NORMAL; -``` -Output: -``` -false -``` - -So our polytope is not normal. We can also find a point that violates the condition. Being normal is equivalent to the fact, that the Hilbert basis of the cone C(Q) obtained from Q by embedding the polytope at height one and the coning over it has all its generators in height one. The property HILBERT_BASIS computes these generators: - - - - -```perl -print $q->HILBERT_BASIS; -``` -Output: -``` -1 2 0 3 -1 2 0 4 -1 2 1 7 -1 2 1 8 -1 3 0 7 -1 3 0 8 -1 3 1 7 -1 3 1 8 -2 5 1 13 -``` - -The last row is the desired vector: [2,5,1,13] is a vector in 2*Q, but it is not a sum of lattice points in Q. The cone C(Q) corresponds to an affine toric variety, and the above tells us that this variety is not normal. Yet, it is very ample, as we can check with - - - - -```perl -print $q->VERY_AMPLE; -``` -Output: -``` -true -``` - -Now assume we are particularly interested in the third facet of Q. We can pick this via - - - - -```perl -$f=facet($q,2); -``` - - -Recall that indexes in `polymake` start at 0, so the third facet has index 2. This is again a very ample polytope: - - - - -```perl -print $f->VERY_AMPLE; -``` -Output: -``` -true -``` - -The result is no surprise, being very ample is inherited by faces. We could also be interested in the facet width of the polytope `$f`. This is the minimum over the maximal distance of a facet to any other vertex. `polymake` knows how to compute this: - -```perl -#print $f->FACET_WIDTH; -``` - -Almost. It tells you that it can only do this for a full dimensional polytope, i.e. for a polytope whose dimension coincides with the ambient dimension. This is not true for our facet: It lives in the same ambient space as `$q`, but has one dimension less. We can remedy this by applying the following: - -```perl -$g=ambient_lattice_normalization($f); -print $g->FACET_WIDTH; -``` -Output: -``` -1 -``` - -The function `ambient_lattice_normalization` returns a full dimensional version of the polytope `$f` in the lattice induced by the intersection of the affine space of `$f` with Z^n. Now `$g` is full dimensional, and we can compute the facet width. Note that there is also a function which normalizes in the lattice spanned by the vertices of the polytope: `vertex_facet_normalization`. This can also be usefull for full dimensional polytopes. E.g. consider the cube we defined above. The sum of the entries of each vertex is odd, so the lattice spannd by the vertices is a sublattice of the integer lattice: - - - - -```perl -$cr=vertex_lattice_normalization($p); -print $cr->VERTICES; -``` -Output: -``` -(4) (0 1) -1 1 0 0 -1 0 1 0 -1 1 1 0 -1 0 0 1 -1 1 0 1 -1 0 1 1 -1 1 1 1 -``` - -`$cr` is the same cube, but we have reduced the lattice. (The first line is a *sparse representation* of a vector: it has length 4, and the only non-zero entry is at position 0 and is 1 (note that indexes start at 0)). - -## Toric Varieties - -`polymake` has only few builtin functions to compute properties of the variety associated to a fan or lattice polytope. There are two extensions available that add more properties, both currently at an early stage: - -* [Toric Varieties and Singular interface](https://github.com/lkastner) by Lars Kastner/Benjamin Lorenz - -* [ToricVarieties-v0.3](http://www.mathematik.tu-darmstadt.de/~paffenholz/software.html) by Andreas Paffenholz. Defines a new property for toric varieties associated to a fan and divisors on that variety. - -Here we will do some computations that do not require one of the extensions. We start by defining a fan. We'll make our live easy and take the normal fan of our cube: - - - - -```perl -application "fan"; -``` - -```perl -$f = normal_fan($p); -print $f->SMOOTH_FAN; -``` -Output: -``` -true -``` - -With the last line we have verified that our fan defines a smooth toric variety. Note that switching the application is not strictly necessary, you can also prepend calls to functions and constructors with `fan::`. The fan object `$f` itself knows its type, and chooses available properties based on this. Any smooth variety is Gorenstein, so we expect the following: - - - - -```perl -print $f->GORENSTEIN; -``` -Output: -``` -true -``` - -Similarly, we could check for Q-Gorensteinness with `Q_GORENSTEIN`. It is also a complete fan: - - - - -```perl -print $f->COMPLETE; -``` -Output: -``` -true -``` - -but currently there is little support to detect completeness in `polymake`. In our case it was already decided during construction, normal fans are complete. You can also check standard features of fans, like their rays. Let us do this for the normal fan of our other example: - - - - -```perl -$g=normal_fan($q); -print $g->RAYS; -``` -Output: -``` --1 0 1/4 -0 -1 1/4 -1 0 0 -1 1 -1/4 -0 1 0 -0 0 -1 -0 -1 0 --1 0 0 -``` - -This is not what we wanted. We would like to see the minimal lattice generators of the rays. We can fix this using - - - - -```perl -print primitive($g->RAYS); -``` -Output: -``` --4 0 1 -0 -4 1 -1 0 0 -4 4 -1 -0 1 0 -0 0 -1 -0 -1 0 --1 0 0 -``` - -Note that the function `primitive` returns a copy of the argument, the RAYS as stored in the fan are unchanged. So you have to apply this function each time you need the primitive generators, or you store them in a new variable. The fan $g$ is not smooth, but still Gorenstein: - - - - -```perl -print $g->SMOOTH_FAN; -``` -Output: -``` -false -``` - -```perl -print $g->GORENSTEIN; -``` -Output: -``` -true -``` - -You can also access the maximal cones of the fan via - - - - -```perl -print $g->MAXIMAL_CONES; -``` -Output: -``` -{0 1 6 7} -{0 1 2 4} -{0 4 7} -{1 2 6} -{2 3 4} -{5 6 7} -{3 4 5 7} -{2 3 5 6} -``` - -The indices in these list refer to the list of rays. Sometimes you might be interested in the walls, i.e. the codimension 2 faces of the fan. Here is one way to get them - - - - -```perl -print rows_numbered($g->HASSE_DIAGRAM->FACES); -``` -Output: -``` -0:-1 -1:0 1 6 7 -2:0 1 2 4 -3:0 4 7 -4:1 2 6 -5:2 3 4 -6:5 6 7 -7:3 4 5 7 -8:2 3 5 6 -9:0 1 -10:0 7 -11:1 6 -12:6 7 -13:0 4 -14:1 2 -15:2 4 -16:4 7 -17:2 6 -18:3 4 -19:2 3 -20:5 7 -21:5 6 -22:3 5 -23:0 -24:1 -25:7 -26:6 -27:4 -28:2 -29:3 -30:5 -31: -``` - -```perl -print $g->HASSE_DIAGRAM->nodes_of_dim($g->DIM-2); -``` -Output: -``` -{23 24 25 26 27 28 29 30} -``` - -where the list of numbers given by the latter are the indices of the codimension 2 faces in the list of all faces given before. There is a more concise way to list those, using some simple perl programming: - - - - -```perl -print map($g->HASSE_DIAGRAM->FACES->[$_], @{$g->HASSE_DIAGRAM->nodes_of_dim($g->DIM-2)}); -``` -Output: -``` -{0}{1}{7}{6}{4}{2}{3}{5} -``` - - - -## Visualization - -If the lattice polytope lives in R^2 or R^3, then we can visualize the polytope together with its lattice points. - - - -```perl -$p->VISUAL->LATTICE_COLORED; -``` - -The command `LATTICE_COLORED` sorted the lattice points into three classes before visualization: lattice points in the interior of the polytope, lattice points on the boundary, and vertices that are not in the lattice. These classes are then visualized with different colors (where we only see two in the above picture, as all vertices of the cube are in the lattice). If you don't need this distinction, `VISUAL->LATTICE` avoids the additional computations. - -## External Packages - -`polymake` can use `4ti2` and `lattE` via a file based interface and `libnormaliz >= 3.1.0` as library, (the file based interface to `normaliz` has been discontinued) for lattice computations and prints all available packages during startup. To tell `polymake` about a newly installed program run `polymake --reconfigure` or issue the command `reconfigure` during the interactive session. polymake may ask you to confirm the paths to the binaries. - - - Application polytope uses following third-party software (for details: help 'credits';) - 4ti2, cddlib, latte, libnormaliz, lrslib, nauty - - -The output at this position depends on the software available on your computer. To see each call to an external program you can set the variable `$Verbose::external=1;`. If you just want to see the credit message instead of the program call, set `$Verbose::credits=2` instead. If this is 1, then a credit is shown when a package is used for the first time, if 0, then all credits are suppressed (but you can find them in data files afterwards). - - - -```perl -$Verbose::external=1; -``` - -```perl -print $p->EHRHART_POLYNOMIAL; -``` -Output: -``` -8*x^3 + 12*x^2 + 6*x + 1 -``` - - -You can ask `polymake` to prefer one package over another by setting `prefer "program";` where program is one of `_4ti2`, `latte` and `normaliz2`. Of course, the corresponding package needs to be installed on your computer. - - -To prefer one program only for some computations you may append one of .integer_points, .hilbert, .ehrhartpoly for rules computing N_LATTICE_POINTS, LATTICE_POINTS, HILBERT_BASIS or EHRHART_POLYNOMIAL. (Or `prefer_now` just for the next computation) - - - - -```perl -print cube(2)->N_LATTICE_POINTS; -``` -Output: -``` -9 -``` - -```perl -prefer_now "libnormaliz"; -print cube(2)->N_LATTICE_POINTS; -``` -Output: -``` -9 -``` - -```perl -print cube(2)->EHRHART_POLYNOMIAL; -``` -Output: -``` -4*x^2 + 4*x + 1 -``` - -# Scripting - -From the technical point of view, there is no difference between -commands you enter in the interactive session and the scripts: in both -may any valid perl expression is accepted. The difference lies more in -the psychology: while for simple interactive commands practically no -knowledge in programming is needed, the scripting requires certain -profoundness in the perl language. - -But please don't be scared: even with minimal programming skills you can -save a lot of time and typing. The very first scripting exercise can -just consist of copying some lines from the interactive history buffer -(available by invoking `history;` command or directly from the file -`~/.polymake/history`) into a separate script file. As you better get -acquainted with perl and your programming experience grows, you'll be -able to realize more and more complex ideas. - -This page is not aimed, however, as an introduction in the perl -language. There is a lot of excellent literature available on this -topic, and even the man pages, otherwise notorious for their -ineligibility for novices, are very instructive and rich in explanatory -examples. Here you'll rather found details which are special to the -polymake's “dialect” of perl. - -## Calling - -A script can be called from the interactive polymake shell or from other -scripts via the special function `script`: - -``` code -script("scriptfile", arg1, ...); -``` - -As arguments any valid perl expressions may be passed. Alternatively, a -script may be executed directly from the UNIX command line: - -``` code -polymake --script scriptfile ARG1 ARG2 -``` - -Here you can only pass strings (like file names) or numeric constants as -arguments. Besides this restriction, you should keep in mind that if you -execute a script in this fashion, the readline library isn't loaded at -all, thus you won't be able to take any interactive actions like -importing extensions or reconfiguring some rules. Normally you will -hardly ever do it in your scripts, but should you need some interaction -in some exotic case, just change the option from `--script` to -`--iscript` . - -## Structure - -A script can contain pretty anything allowed by perl syntax rules. -However, to get access to polymake classes and functions, it needs a -preamble: - -``` code -use application "NAME"; -``` - -It sets a default application for the rest of the enclosing lexical -context (that is, normally, up to the next `use application` statement -or the end of the script file, but may also be just the enclosing -block). The notion of the default application has exactly the same -meaning as the [current -application](//polymake.org/doku.php/shell#switching_applications "shell") -for the interactive shell: Functions and class names defined in or -imported into the default application may be used without qualification, -while names from other applications must be prefixed by the application -name. - -The script code is compiled in the package `Polymake::User`, the same as -the interactive shell expressions are evaluated in. Thus the scripts can -access non-local variables introduced in the shell and vice versa, -having run the script once, you can use the variables and subroutines -defined in the script. If you want to define additional packages, please -define them as subpackages of `Polymake::User` or completely outside -`Polymake::`, to prevent accidental clashes with polymake internal -classes. - -The script may define subroutines and/or contain file-level code. The -latter is assembled together to a anonymous subroutine which is executed -each time you call the `script` function; its return value is the last -expression executed in the file-level code (or in a `return` statement, -if any). The arguments are passed in the global array `@ARGV`, not in -`@_` as for usual subroutines. If you intend to use your script in both -interactive and batch mode, you might want to build in some flexible -recognition of argument types, for example, allowing for both ready -objects and filenames to be passed: - -``` code - my $p=shift @ARGV; - $p=load($p) unless is_object($p); -``` - -Since the script code may be repeatedly executed arbitrarily many times, -you should put a special attention to variables requiring one-time -initialization. Such initializations should be either put in a `BEGIN` -block or guarded by `||=` or `//=` operators. Also please note that if -you introduce `my` variables on a file level and define other -subroutines in the script which refer to these variables, the -subroutines capture the values assigned during the first execution of -the script. Even if your script changes the values of these `my` -variables during each execution, the captured values in the subroutines -will remain unaffected. (It'll be of no surprise for seasoned perl -hackers familiar with the notion of *closures*). - -You can modify the script file in a text editor without leaving the -polymake session. The `script` function stores the timestamps of all -executed script files, so the changes will be detected by the next call -to `script` and the script file will be reloaded automatically. - -## Location - -Scripts can be kept in arbitrary folders. Unless the script you want to -execute resides in the current directory, you must specify its full path -in the `script` command. TAB completion assists you at this. There are, -however, special locations, where the scripts are found just by name. -Moreover, some locations impose special semantics on the scripts. - -Neutral scripts, that is, those capable of working with arbitrary -applications, and scripts explicitly switching the applications, can be -kept at the following places: - -- `$InstallTop/scripts` – standard neutral scripts shipped with polymake - -- `@lookup_scripts` – additional directories of your choice containing - your private scripts. This list is a [custom - variable](//polymake.org/doku.php/user_guide/howto/shell_custom#custom_variables "user_guide:howto:shell_custom"). - -- `$Extension/scripts` – neutral scripts coming from an - [extension](//polymake.org/doku.php/user_guide/extend/extensions "user_guide:extend:extensions") - -Application-specific scripts are kept in the applications' subtrees: - -- `$InstallTop/apps/APPNAME/scripts` – standard scripts shipped with - polymake - -- ` $Extension/apps/APPNAME/scripts` – scripts coming from an extension - -These scripts don't need the preamble `use application`, it is -automatically imposed. An application-specific script can be executed -with the `script` command if its application is the current one or is -imported by the current application. - -Your collection of scripts will probably grow over the time, some -scripts sharing common code parts. The common code is usually extracted -in separate `.pl` or `.pm` files included with `require` statement. The -lookup rules for these files is a bit different: the directories to be -searched have to be inserted into the global array `@INC`. The -appropriate `push` or `unshift` statements can be placed in your -personal startup script `~/.polymake/init.pl`. We recommend, however, to -create a private extension and store the scripts and the included files -in subdirectories `scripts` and `perllib` respectively. In this setting -you don't have to manipulate any lookup list. - diff --git a/apn/lean/docs/prover9/LICENSE b/apn/lean/docs/prover9/LICENSE deleted file mode 100644 index d511905c..00000000 --- a/apn/lean/docs/prover9/LICENSE +++ /dev/null @@ -1,339 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. diff --git a/apn/lean/docs/prover9/prover9-manual.md b/apn/lean/docs/prover9/prover9-manual.md deleted file mode 100644 index 932be9e3..00000000 --- a/apn/lean/docs/prover9/prover9-manual.md +++ /dev/null @@ -1,3218 +0,0 @@ - - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Introduction - -[Prover9](http://www.cs.unm.edu/~mccune/prover9/) is a -resolution/paramodulation automated theorem prover for first-order and -equational logic. Prover9 is a successor of the -[Otter](http://www.cs.unm.edu/~mccune/otter/) Prover -\[[McCune-Otter33](references.html#McCune-Otter33)\]. - -## Getting Started - -Prover9 has a fully [automatic mode](auto.html) in which the user simply -gives it formulas representing the problem. See the Section [Clauses and -Formulas](syntax.html). - -An good way to learn about Prover9 is to browse and study the [example -input and output -files](http://www.cs.unm.edu/~mccune/prover9/examples/). *Users are -encouraged to contribute examples from their own work with Prover9 (and -Mace4).* - -## Related Programs - -Several programs come bundled with Prover9. The most important is -[Mace4](mace4.html), which looks for finite models and counterexamples. -Mace4 can help avoid wasting time searching for a proof with Prover9 by -first finding a counterexample or by first helping to debug logical -specifications. - -Another useful program is [Prooftrans](prooftrans.html), which can -transform proofs found by Prover9 in various ways, including producing -more detailed proofs, simplifying the justifications, renumbering the -steps, producing proofs in XML, and producing proofs for input to other -programs. - -## Terms of Use - -Prover9, Mace4, related programs, and the LADR libraries (with which -they were all constructed) are distributed under the terms of the [**GNU -General Public License (v2)**](http://www.gnu.org/copyleft/gpl.html). - -## Other Theorem Provers - -- [E](http://www.eprover.org) is a very good all-around prover. -- [Waldmeister](http://www.mpi-sb.mpg.de/~hillen/waldmeister/) is a fast - prover for equational logic. -- [Vampire](http://en.wikipedia.org/wiki/Vampire_theorem_prover) has - lately been winning the MIX category of - [CASC](http://www.cs.miami.edu/~tptp/CASC/). -- [Paradox](http://www.cs.chalmers.se/~koen/paradox/) is an excellent - program for finding finite models and counterexamples. -- See the [CASC Website](http://www.cs.miami.edu/~tptp/CASC/) for - information on lots of other good provers. - -## Format Conventions for this Manual - -Many parts of this manual are displayed in boxes with different -background colors. - -A display like the following indicates part of an input or output file. - -``` my_file -formulas(sos). - all x all y (subset(x,y) <-> (all z (member(z,x) -> member(z,y)))). -end_of_list. - -formulas(goals). - all x all y all z (subset(x,y) & subset(y,z) -> subset(x,z)). -end_of_list. -``` - -A display like the following indicates a job that is run on a command -line, for example, a command to run a Prover9 job. - -``` my_job -prover9 -f subset_trans.in > subset_trans.out -``` - -A display like the following indicates some output that appears on the -computer screen, for example, a message from Prover9. - -``` my_screen --------- Proof 1 -------- -THEOREM PROVED ------- process 3666 exit (max_proofs) ------ -``` - -Displays like the following contain algorithms. - -``` my_code -Simplify clause (c): - demodulate c - merge identical literals -``` - -A display like the following notes an important difference between -Prover9 and Otter. - -> Prover9's automatic mode is set by default. Otter's automatic mode -> must be explicitly set. - ------------------------------------------------------------------------- - -Next Section: [Installation](install.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Running Prover9 - -The standard way of running Prover9 is to (1) prepare an input file -containing the logical specification of a conjecture and the search -parameters, (2) issue a command that runs Prover9 on the input file and -produces an output file, (3) look at the output, and (4) maybe run -Prover9 again with different search parameters. - -A [graphical user interface (GUI) for -Prover9](http://www.cs.unm.edu/~mccune/prover9/gui/) is under -development, but it is not described in this manual. Nearly all of the -information in this manual applies also when using the GUI. - -## An Input File - -Here is an input file; assume it is named `subset_trans.in`. -(Use a plain text editor, not a word processor, to create input files.) - -``` my_file -formulas(sos). - all x all y (subset(x,y) <-> (all z (member(z,x) -> member(z,y)))). -end_of_list. - -formulas(goals). - all x all y all z (subset(x,y) & subset(y,z) -> subset(x,z)). -end_of_list. -``` - -## A Basic Prover9 Command - -Here is a command to run Prover9 on the preceding file and send the -output to a file called `subset_trans.out`. - -``` my_job -prover9 -f subset_trans.in > subset_trans.out -``` - -When you run the preceding command, a message like the following should -appear immediately on your screen. - -``` my_screen --------- Proof 1 -------- -THEOREM PROVED ------- process 3666 exit (max_proofs) ------ -``` - -The output file [subset_trans.out](subset_trans.out) should contain the -proof (and a lot of other information about the job). - -## Taking Input from Standard Input - -Prover9 jobs can be run in a slightly different way, taking input from -"standard input" instead of a named file, as follows. - -``` my_job -prover9 < subset_trans.in > subset_trans.out2 -``` - -The disadvantage of using this method is that the name of the input file -is not given in the output file. - -## More Than One Input File - -The input can occur in more than one file: - -``` my_job -prover9 -f subset.in trans.in > subset_trans.out3 -``` - -All arguments after the "`-f`" are taken as input filenames, and there -can be as many as you like. When multiple filnames are given on the -command line, a list of objects (clauses, formulas, or terms) cannot be -split across more than one file. - -## Time Limit on the Command Line - -Prover9 also accepts a time limit, in seconds, on the command line. The -following command limits the job to about 10 seconds. - -``` my_job -prover9 -t 10 -f subset_trans.in > subset_trans.out4 -``` - -If "`-t`" and "`-f`" are both in the command, the "`-t`" must occur -first. - -## Getting Statistics During the Search - -*This section applies to Unix-like systems only.* - -If a Prover9 process is running in the background, one can tell it to -send search statistics (without killing the job) to the output file -sending a "USR1" signal to the process. For example, - -``` my_job -% prover9 -f p3a.in > p3a.outb & - [1] 31613 -% kill -USR1 31613 - A report (17.75 seconds) has been sent to the output. -``` - -## Calling Prover9 From Another Program - -If Prover9 is called from another program (e.g., a shell script, a Perl -script, or a Python script), Prover9's exit codes can tell the other -program the reason Prover9 terminates. The following table shows the -exit codes. - -Exit Code - -Reason for Termination - -0 (MAX_PROOFS) - -The specified number of proofs -([**`max_proofs`**](limits.html#max_proofs)) was found. - -1 (FATAL) - -A fatal error occurred (user's syntax error or Prover9's bug). - -2 (SOS_EMPTY) - -Prover9 ran out of things to do (sos list exhausted). - -3 (MAX_MEGS) - -The [**`max_megs`**](limits.html#max_megs) (memory limit) parameter was -exceeded. - -4 (MAX_SECONDS) - -The [**`max_seconds`**](limits.html#max_seconds) parameter was exceeded. - -5 (MAX_GIVEN) - -The [**`max_given`**](limits.html#max_given) parameter was exceeded. - -6 (MAX_KEPT) - -The [**`max_kept`**](limits.html#max_kept) parameter was exceeded. - -7 (ACTION) - -A Prover9 [action](actions.html) terminated the search. - -101 (SIGINT) - -Prover9 received an interrupt signal. - -102 (SIGSEGV) - -Prover9 crashed, most probably due to a bug. - -The calling program will probably want to look in Prover9's output, for -example, to extract a proof. See the page on [Prover9 output -files](output.html). - ------------------------------------------------------------------------- - -Next Section: [Input Files](input.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Prover9 Input Files - -Prover9 takes its input from one or more (usually one) files. If there -is more than one input file, lists of objects (formulas, weighting -rules, etc.) cannot be split across more than one file. The page -[Running Prover9](running.html) shows how to specify the files in the -commands to run Prover9. - -## Comments and Whitespace - -There are two kinds of comment: - -- *Line comment*. If the first '`%`' (percent sign) on a line is not the - start of a block comment ('`%BEGIN`'), everything from that symbol - through the end of the line is ignored. -- *Block comment*. If the parser sees the string '`%BEGIN`', that is not - in a line comment, it will ignore everything up through the next - occurrence of '`END%`'. Line breaks are irrelevant. If there is no - '`END%`', the rest of the file is ignored, without causing an error. - -Comments are not echoed to the output file. Clauses can have [label -attributes](attributes.html) which can serve as different kind of -comment which *does* appear in the output file. - -Whitespace (spaces, newlines, tabs, etc.) is optional in most places. -The important exception is that whitespace is required around some -operations in clauses and formulas (see the page [Clauses and -Formulas](syntax.html)). - -## A Simple Example - -The most basic kind of input file consists of list of -[clauses](glossary.html#clause) named "`sos`" representing the negation -of the conjecture, as in the following example. - -``` my_file -formulas(sos). % clauses to be placed in the sos list - -man(x) | mortal(x). - man(george). - -mortal(george). -end_of_list. -``` - -Prover9 will take the clauses, use its automatic mode to decide on the -inference rules, and then search for a refutation. - -The preceding example can also be stated in a more natural way by using -a non-clausal formula for the man-implies-mortal rule and the [`goals` -list](goals.html) for the conclusion, as follows. - -``` my_file -formulas(assumptions). % synonym for formulas(sos). - man(x) -> mortal(x). % open formula with free variable x - man(george). -end_of_list. - -formulas(goals). % to be negated and placed in the sos list - mortal(george). -end_of_list. -``` - -Prover9 will transform the formulas in this input to the same clauses as -in the basic input above before starting the search for a refutation. - -> In Otter and in earlier versions of Prover9, "clauses" and "formulas" -> were distinct types of object, and formulas could not have free -> variables. Now, clauses are a subset of formulas, and Prover9 decides -> which formulas are non-clausal and takes the appropriate actions to -> transform them to clauses. - -## Types of Input - -Prover9 input consists of lists of objects (formulas or terms) and -commands. - -### Lists of Objects - -Lists of objects start with a type (`formulas` or `terms`) and name -(`sos`, `goals`, `weights`, etc.), and end with `end_of_list`. The -following display show an example of each type of accepted list, with -one object in each list. - -``` my_file -formulas(sos). p(x). end_of_list. % the primary input list -formulas(assumptions). p(x). end_of_list. % synonym for formulas(sos) -formulas(goals). p(x). end_of_list. % some restrictions (see Goals) -formulas(usable). p(x). end_of_list. % seldom used -formulas(demodulators). f(x)=x. end_of_list. % seldom used, must be equalities -formulas(hints). p(x). end_of_list. % should be used more often (see Hints) - -list(weights). weight(a) = 10. end_of_list. % see Weighting -list(kbo_weights). a = 3. end_of_list. % see Term Ordering -list(actions). given = 100 -> set(print_kept). end_of_list. % see Actions -list(interpretations). interpretation(2,[],[relation(p,[1])]). end_of_list. % see Semantics -``` - -If the input contains more than one list of a particular type/name, the -lists are simply concatenated by Prover9 as they are read. - -### Commands - -Eleven types of command are accepted. Here is an example of each. - -``` my_file -op(400, infix_right, ["+", "--"]). % declare parse precedence and type (see Clauses and Formulas) - -redeclare(negation, "~"]). % change the negation symbol (see Clauses and Formulas) - -set(print_kept). % set a flag - -clear(auto_inference). % clear a flag - -assign(max_weight, 40). % integer parameter - -assign(stats, some). % string parameter - -assoc_comm(*). % not currently used for Prover9 - -commutative(g). % not currently used for Prover9 - -predicate_order([=,<=,P,Q). % predicate symbol precedence (see Term Ordering) - -function_order([0,1,a,b,f,g,*,+]). % function symbol precedence (see Term Ordering) - -lex([0,1,a,b,f,g,*,+]). % synonym for "function_order" - -skolem([a,b,f,g]). % declare symbols to be Skolem functions (rarely used) -``` - -## Order of Commands and Lists of Objects - -For the most part, the order of things in the input file(s) is -irrelevant. For example, commands can usually be mixed with lists of -objects. The situations in which order matters are listed here. - -- The `op(precedence, type, symbols)` commands must occur before any - clauses or formulas that contain the affected symbols. -- Some of the flags and parameters alter other flags and parameters. The - alterations can be undone by placing the appropriate command after the - command that alters. The output file clearly shows what happens in - these cases. - -Note that changing the order of clauses or formulas within a list, -changing the order of literals in a clause, or changing the order of -subformulas in a formula can change the search, occasionally in -substantial ways. - -## Conditional Inclusion - -Many input files can be used for multiple programs (e.g., Prover9 and -Mace4). The following construct says to include the enclosed input for -the given program only. - -``` my_file -if(program-name). - ... conditionally-included input ... -end_if. -``` - -For example, to specify that Mace4 and Prover9 have different time -limits, one can write - -``` my_file -if(Mace4). - assign(max_seconds, 30). -end_if. - -if(Prover9). - assign(max_seconds, 3600). -end_if. -``` - -The conditional-inclusion construct cannot occur within a list of -objects (formulas, weighting rules, etc.). - ------------------------------------------------------------------------- - -Next Section: [Clauses & Formulas](syntax.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Clauses and Formulas - -The [Glossary Page](glossary.html) contains definitions of -[term](glossary.html#term), [atomic -formula](glossary.html#atomic%20formula), -[literal](glossary.html#literal), [clause](glossary.html#clause), and -[formula](glossary.html#formula) from a logical point of view. This page -contains descriptions of how those kinds of things are parsed and -printed, and we refer to them collectively as *objects*. - -> In Otter and in earlier versions of Prover9, "clauses" and "formulas" -> were distinct types of object, and "formulas" could not have free -> variables. Now, clauses are a subset of formulas. - -Here are the important points about clauses and formulas. - -- Clauses are a subset of formulas. All input formulas, including - clauses, appear in a list headed by `formulas(`*`list_name`*`)`. -- There is a rule for distinguishing variables from constants, because - clauses and other formulas can have free variables (variables not - bound by quantifiers). The default rule is that variables start with - (lower case) `u` through `z`. For example, in the formula `P(a,x)`, - the term `a` is a constant, and `x` is a variable. (See also the flag - [**`prolog_style_variables`**](syntax.html#prolog_style_variables).) -- Free variables in clauses and formulas are assumed to be universally - quantified at the outermost level. -- Prover9's inference rules operate on clauses. If non-clausal formulas - are input, Prover9 immediately translates them clauses by - [NNF](glossary.html#NNF), - [Skolemization](glossary.html#skolemization), and - [CNF](glossary.html#CNF) conversions. - -## Parsing and Printing Objects - -The *prefix standard form* of an object with an n-ary symbol, say `f`, -at the root is - -``` my_file -f( argument_1, ..., argument_n ) -``` - -Whitespace (spaces, tabs, newline, etc.) is accepted anywhere except -within symbols. - -Prover9 will accept any term or formula written prefix standard form. -However formulas and many terms can be written in more convenient ways, -for example, "`a=b | a!=c'`" instead of "`|(=(a,b),-(=(a,'(c))))`". - -Prover9 uses a general mechanism in which binary and unary symbols can -have special parsing properties such as "infix", -"infix-right-associated", "postfix". In addition, each of those symbols -has a precedence so that many parentheses can be omitted. (The mechanism -is similar to those used by most Prolog systems.) - -Many symbols have built-in parsing properties (see the [table -below](#built_in)), and the user can declare parsing properties for -other symbols with the "op" command. - -Clauses and formulas make extensive use of the built-in parsing -properties for the equality relation and the logic connectives. Instead -of first presenting the general mechanism, we will present the syntax -for formulas under the assumption of the built-in parsing properties. -The general mechanism is described below in the section [Infix, Prefix, -and Postfix Declarations](#declarations). - -### Symbols - -Symbols include variables, constants, function symbols, predicate -symbols, logic connectives. Symbols do not include parentheses or -commas. - -Prover9 recognizes several kinds of symbol. - -- An *ordinary symbol* is a (maximal) string made from the characters - `a`-`z`, `A`-`Z`, `0`-`9`, `$`, and `_`. -- A *special symbol* is a (maximal) string made from the *special - characters*: `` {+-*/\^<>=`~?@&|!#';} ``. -- A *quoted symbol* is any string enclosed in double quotes. -- The *empty list symbol* is `[]`. This is a special case. - -The reason for separating ordinary and special symbols is so that -strings like `a+b`; that is, `+(a,b)`, can be written without any -whitespace around the `+`. - -A symbol cannot have both ordinary and special characters, for example -`R+` (unless it is a quoted symbol). - -Objects (terms or formulas) are constructed from symbols, parentheses, -and commas. - -### Overloaded Symbols - -In most cases, symbol overloading is not allowed. For example a symbol -cannot be both a function symbol and a predicate symbol, or both a -constant and a binary function symbol. There are a few exceptions. - -- The logic connectives can also be used as function or predicate - symbols of the same arity. For example, `-` is typically used as unary - arithmetic minus well as for logical negation. - -> Prover9 is much more strict about overloading symbols than Otter is. - -### Symbols With Meaning - -Several symbols have built-in meaning. These are the equality symbols -(`=`, `!=`) and logic connectives (`-`, `|`, `&`, `->`, `<-`, `<->`, -`all`, `exists`). These symbols can be changed as described in the -section [Redeclaring Built-in Symbols](#redeclare). (Parentheses, comma, -period, and the list construction symbols cannot be redeclared.) - -Terms - -Any term can be written in prefix standard form, for example, -`f(g(x),y)` and `*('(x),y)`. If symbols in the term have -parsing/printing properties (either [built-in](#built_in)) or declared -with the `op` command), the term can be written in infix/prefix/postfix -form with assumed precedence, for example, `x'*y`, which represents -`*('(x),y)` under the built-in parsing/printing properties. - -A list notation similar to Prolog's can be used to write terms that -represent lists. Note that the "cons" operator is "`:`", instead of -"`|`" as in Prolog. - -Term - -Standard Prefix Form - -What it Is - -`[]` - -`$nil` - -the empty list - -`[a,b,c]` - -`$cons(a,$cons(b,$cons(c,$nil)))` - -list of three objects - -`[a:b]` - -`$cons(a,b)` - -first, rest - -`[a,b:c]` - -`$cons(a,$cons(b,c))` - -first, second, rest - -Lists are frequently used in Prover9 commands such as the -[`function_order`](input.html#lists) command, and they are sometimes -also used in clauses and formulas. - -### Atomic Formulas - -Equality is a built-in special case. The binary predicate symbol `=` is -usually written as an infix relation. The binary symbol `!=` is an -abbreviation for "not equal"; that is, the formula `a!=b` stands for -`-(a=b)`, or more precisely, `-(=(a,b))`. From the semantics point of -view, the binary predicate symbol `=` is the one and only equality -symbol for the inference rules that use equality. - -### Clauses - -The disjunction (OR) symbol is `|`, and the negation (NOT) symbol is -`-`. The disjunction symbol has higher precedence than the equality -symbol, so equations in clauses do not need parentheses. Every clause -ends with a period. Examples of clauses follow (Prover9 adds some extra -space when printing clauses). - -``` my_file -formulas(sos). - p|-q|r. - a=b|c!=d. - f(x)!=f(y)|x=y. -end_of_list. -``` - -### Formulas - -Meaning - -Connective - -Example - -negation - -`-` - -`(-p)` - -disjunction - -`|` - -`(p | q | r)` - -conjunction - -`&` - -`(p & q & r)` - -implication - -`->` - -`(p -> q)` - -backward implication - -`<-` - -`(p <- q)` - -equivalence - -`<->` - -`(p <-> q)` - -universal quantification - -`all` - -`(all x all y p(x,y))` - -existential quantification - -`exists` - -`(exists x exists y p(x,y))` - -When writing formulas, the [built-in parsing declarations](#built_in) -allow many parentheses to be omitted. For example, the following two -formulas are really the same formula. - -``` my_file -formulas(sos). - all x all y (p <-> -q | r & -s) . -(all x (all y (p <-> ((-q) | (r & (-s)))))). -end_of_list. -``` - -> For Prover9 formulas, each quantified variable must have its own -> quantifier; Otter allows quantifiers to be omitted in a sequence of -> quantified variables with the same quantifier. For example, Otter -> allows `(all x y z p(x,y,z))`, and Prover9 requires -> `(all x all y all z p(x,y,z))`. - -Infix, Prefix, and Postfix Declarations - -Several symbols are understood by Prover9 as having special parsing -properties that determine how terms involving those symbols can be -arranged. In addition, the user can declare additional symbols to have -special parsing properties. - -### Parsing Declarations - -The "op" command is used to declare parse types and precedences. - -``` my_file -op( precedence, type, symbols(s) ). % declare parse type and precedence -``` - -- 1 ≤ *`precedence`* ≤ 998. -- *`type`* is one of { - `infix, infix_left, infix_right, prefix, prefix_paren, postfix, postfix_paren, ordinary` - }. -- *`symbol(s)`* is either a symbol or a list of symbols. Each - multi-character special symbol must be enclosed in double quotes. - -> Prover9 does not allow different symbol types with the same -> precedence, for example, -> -> ``` my_file -> op(325, postfix, '). -> op(325, prefix, ~). -> ``` -> -> This restriction prevents ambiguous strings such as `~x'`. - -The following table shows an example of each type of parsing property -(and ignores precedence). - -Type - -Example - -Standard Prefix - -Comment - -`infix` - -`a*(b*c) ` - -`*(a,*(b,c))` - -like Prolog's `xfx` - -`infix_left` - -`a*b*c ` - -`*(*(a,b),c)` - -like Prolog's `yfx` - -`infix_right` - -`a*b*c ` - -`*(a,*(b,c))` - -like Prolog's `xfy` - -`prefix` - -`--p ` - -`-(-(p)) ` - -like Prolog's `fy` - -`prefix_paren` - -`-(-p) ` - -`-(-(p)) ` - -like Prolog's `fx` - -`postfix` - -`a'' ` - -`'('(a)) ` - -like Prolog's `yf` - -`postfix_paren` - -`(a')' ` - -`'('(a)) ` - -like Prolog's `xf` - -`ordinary` - -`*(a,b) ` - -`*(a,b) ` - -takes away parsing properties - -Higher precedence means closer to the root of the object, and lower -precedence means the the symbol binds more closely. For example, assume -that the following declarations are in effect. - -``` my_file -op(790, infix_right, "|" ). % disjunction in formulas or clauses -op(780, infix_right, "&" ). % conjunction in formulas -``` - -Then the string `a & b | c` is an abbreviation for `(a & b) | c`. - -The built-in parsing declarations are shown in the following box. The -ones with comments have built-in meanings; the others are for general -use as function or predicate symbols. - -``` my_file -op(810, infix_right, "#" ). % for attaching attributes to clauses - -op(800, infix, "<->" ). % equivalence in formulas -op(800, infix, "->" ). % implication in formulas -op(800, infix, "<-" ). % backward implication in formulas -op(790, infix_right, "|" ). % disjunction in formulas or clauses -op(780, infix_right, "&" ). % conjunction in formulas - -% Quantifiers (a special case) have precedence 750. - -op(700, infix, "=" ). % equal in atomic formulas -op(700, infix, "!=" ). % not equal in atomic formulas -op(700, infix, "==" ). -op(700, infix, "<" ). -op(700, infix, "<=" ). -op(700, infix, ">" ). -op(700, infix, ">=" ). - -op(500, infix, "+" ). -op(500, infix, "*" ). -op(500, infix, "@" ). -op(500, infix, "/" ). -op(500, infix, "\" ). -op(500, infix, "^" ). -op(500, infix, "v" ). - -op(350, prefix, "-" ). % logical negation in formulas or clauses -op(300, postfix, "'" ). -``` - -The built-in parsing declarations can be overridden with ordinary "op" -commands. Be careful, however, when overriding parsing declarations for -symbols with built-in meanings. For example, say you wish to use "#" as -an infix function symbol and give the following the declaration. - -``` my_file -op(500, infix, "#"). -``` - -Then clauses with attributes might have be written with more -parentheses, for example, as - -``` my_file -(p(a) | q(a)) # (label(a) # label(b)). -``` - -If you wish to use one of the symbols with built-in parsing declarations -as an ordinary prefix symbol, you can undo the declaration by giving an -"op" command with type "ordinary". The following example clears the -parse types for two symbols. - -``` my_file -op(ordinary, ["*","+"]). % there is no precedence argument for type "ordinary" -``` - -Finally, the following example shows that parsing declarations can be -changed anywhere in the input, with immediate effect. This can be useful -for example, if lists of clauses come from different sources. - -``` my_file -op(400,infix_left,"*"). % assume left association for following clauses - -formulas(sos). - P(a * b * c). -end_of_list. - -op(400,infix_right,"*"). % assume right association for following clauses - -formulas(sos). - Q(d * e * f). -end_of_list. - -op(400,infix,"*"). % from here on, include all parentheses (input and output) -``` - -An excerpt from the output of the preceding example shows how the -clauses are printed after the last "op" command. - -``` my_file -formulas(sos). -P((a * b) * c). [assumption]. -Q(d * (e * f)). [assumption]. -end_of_list. -``` - -## Prolog-Style Variables - -``` my_option -set(prolog_style_variables). -clear(prolog_style_variables). % default clear -``` - -> A rule is needed for distinguishing variables from constants in -> clauses and formulas with free variables. If this flag is clear, -> variables in clauses start with (lower case) 'u' through 'z'. If this -> flag is set, variables in clauses start with (upper case) 'A' through -> 'Z'. -> -> Prover9 decides whether symbols are constants or variables after it -> has read all of its input, so the state of the flag -> [**`prolog_style_variables`**](syntax.html#prolog_style_variables) at -> the end of the input determines the rule that is used for *all* -> formulas. For example, in the following input, -> -> ``` my_file -> formulas(sos). -> p(x,A). -> end_of_list. -> -> set(prolog_style_variables). -> -> formulas(sos). -> q(y,B). -> end_of_list. -> ``` -> -> the term `x` is a constant, and `A` is a variable. - -Redeclaring Built-in Symbols - -NOTE: Keep in mind the difference between *semantic* properties of -symbols (e.g., logic connectives) and *parsing/printing* properties of -symbols (e.g., infix with high precedence). Those two kinds of property -are independent (by default, many symbols have both). - -Most of the symbols with built-in meaning can be changed to other -symbols. The symbols that can be changed are shown in the following -table. - -Operation - -Default Symbol - -true - -`$T` - -false - -`$F` - -negation - -`-` - -disjunction - -`|` - -conjunction - -`&` - -implication - -`->` - -backward_implication - -`<-` - -equivalence - -`<->` - -universal_quantification - -`all` - -existential_quantification - -`exists` - -equality - -`=` - -negated_equality - -`!=` - -attribute - -`#` - -To change the symbol associated with an operation, one uses the -following command. - -``` my_file -redeclare( operation, symbol ). % associate a different symbol with an operation -``` - -For example, the following command says that "`AND`" will be used for -conjunction. - -``` my_file -redeclare(conjunction, AND). % change the conjunction symbol to AND. -``` - -As with the "`op`" command, if the new symbol is a multicharacter -[special symbol](#special_symbol), it must be enclosed in double quotes, -as in the following example. - -``` my_file -redeclare(conjunction, "&&"). % change the conjunction symbol to &&. -``` - -When in doubt, quote the symbol, because unnecessary quotes are ignored -in the "`redeclare`" and "`op`" commands. - -### Parsing/Printing Properties and Redeclarations - -Many of the default symbols for the built-in operations have default -printing/parsing properties, for example, the default properties for -default conjunction symbol are - -``` my_file -op(780, infix_right, "&" ). % conjunction in formulas -``` - -When a redeclaration for such an operation occurs, the parsing/printing -properties are copied from the old symbol to the new symbol. For -example, when conjunction is changed to `AND`, the following is -*automatically* applied. - -``` my_file -op(780, infix_right, AND ). -``` - -If the user wishes some other printing/parsing properties for the new -symbol, the appropriate "`op`" command can be placed after the -"`redeclare`" command. - -### Redeclaration Example - -The following example shows redeclarations of many of the operations. - -``` my_job -prover9 -f redeclare.in > redeclare.out -``` - -### Location of Redeclare Commands - -Most of the operations can be redeclared repeatedly throughout the -input. The declarations in effect when a formula is read will be used, -ane the ones in effect at the end of the input will be used for all -subsequent output. - -*An exception*: If the operations "`equality`" or "`negated_equality`" -are redeclared, it must be done before any formulas containing those -symbols are read. - ------------------------------------------------------------------------- - -Next Section: [Auto Modes](auto.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Goals and Denials - -This section shows how the conclusion(s) of a conjecture can be stated -in positive form, how one can search for direct proofs as opposed to -bidirectional proofs, and how multiple conclusions are stated and -handled. - -Terminology - -- *Conclusion*: this term is used informally. -- *Goal*: this term refers to a conclusion stated in positive form. -- *Denial clause*: this term refers to a negative clause in a [Horn - set](glossary.html#horn), because such clauses usually correspond to - the negation of a conclusion. - -## Goals: Stating Conclusions in Positive Form - -> In Otter, the conclusions are always stated in negated form. - -Prover9 allows the user to state conclusions in positive form by using -the list `formulas(goals)`. However, Prover9 always works by refutation, -so the clauses or formulas in the `goals` lists are negated as described -below, and the results are appended to the `sos` clause list before the -search starts. In other words, goals are "syntactic sugar" for input, -and have nothing to do with the way Prover9 conducts its search for -refutations. - -When the conclusion is given in positive form, the user has no control -over the [Skolem](glossary.html#skolemization) symbols (if any) that -Prover9 introduces. If the user needs some control of the Skolem -symbols, for example, to insert them into the symbol precedence at a -particular spot, or to include them in the weighting function, the user -should do the Skolemizing and give the conclusion in negated form. - -If there is just one formula in `formulas(goals)`, the meaning is clear: -the formula is processed by first taking its universal closure, then -negating. The formula is then handled exactly as if it had been input in -`formulas(sos)`, that is, by Skolemizing and transforming to clauses. - -### Multiple Goals - -If there is more than one formula in `formulas(goals)`, the meaning is -not clear. Is the conclusion the disjunction of those formulas? Or the -conjunction? *The answer: disjunction*: if any goal is proved, the proof -is reported, printed, and counted. - -Multiple *complex* goals are not allowed, because the quantification of -free variables can be very confusing. Therefore Prover9 enforces the -following rule. - -> *If there is more than one formula in the goals list, each must be a -> positive universal conjunctive formula, that is a formula constructed -> from atomic formulas, universal quantification, and conjunction only.* - -To avoid this restriction, one can always write the conclusion clearly -as a single goal formula containing any of the logic connectives and -quantification. However, if the conjecture involves multiple complex -conclusions, we recommend, for search efficiency, separate Prover9 -searches. - -If there are multiple goals, each is processed separately by applying -universal closure, negation, and transformation to clauses. After this -processing, Prover9 forgets that there were multiple goals and simply -searches for refutations. - -When there are multiple goals, and when the user wishes to prove more -than one goal, the parameter [**`max_proofs`**](goals.html#max_proofs) -should be set to an appropriate value. (The flag -[**`auto_denials`**](goals.html#auto_denials) (default set) can do so -automatically.) - -## Multiple Proofs - -``` my_option -assign(max_proofs, n). % default n=1, range [-1 .. INT_MAX] -``` - -> This parameter tells Prover9 to stop searching when the *n*-th proof -> has been found. - -## Denials: Negative Clauses in Horn Sets - -Denial clauses (negative clauses in Horn sets) can be derived from -goals, or they can be input directly as negative clauses. - -### Multiple Proofs of the Same Conclusion - -``` my_option -set(reuse_denials). -clear(reuse_denials). % default clear -``` - -> If this flag is set, when a denial clause (a negative clause in a Horn -> set) is used in a proof, and when -> [**`max_proofs`**](goals.html#max_proofs) says to search for more -> proofs, subsequent proofs may be of the same conclusion. (Multiple -> proofs of the same conclusion may be useful when one is searching for -> *short* proofs.) -> -> If this flag is clear, then when a proof is found, the denial and all -> of its descendants are disabled so that they will not appear in -> subsequent proofs. -> -> This flag is independent of the flag -> [**`restrict_denials`**](goals.html#restrict_denials). - -### Auto_denials - -``` my_option -set(auto_denials). % default set -clear(auto_denials). -``` - -> If this flag is set (the default), negative clauses in [Horn -> sets](glossary.html#horn) receive some special initial processing. -> -> If a Horn set has more than one denial (negative) clause, we assume -> they correspond to separate conclusions, and the user wishes to have a -> separate proof of each conclusion. Therefore, if -> [**`max_proofs`**](goals.html#max_proofs) has not been changed from -> its default value of 1, we assign to -> [**`max_proofs`**](goals.html#max_proofs) the number of negative -> clauses. (Note that when -> [**`reuse_denials`**](goals.html#reuse_denials) is clear (the -> default), Prover9 prevents multiple proofs of the same conclusion.) -> -> Also, if a negative clause in a Horn set has label attribute but no -> answer attribute, the clause is given an answer attribute -> corresponding to the first label attribute. This saves the user from -> changing "label" to "answer" when moving formulas from the `sos` list -> to the `goals` list. - -### Forward or Direct Proofs - -The following flag restricts the use of negative clauses, with the aim -of finding proofs that are more direct; that is, proofs that go forward -from the hypotheses to the conclusion rather than proofs that reason -backward from the conclusion. - -Ordinarily, the term *denial* refers to a negative clause in a Horn set. -Here, we use it for any negative clause. Originally, the flag -[**`restrict_denials`**](goals.html#restrict_denials) applied only to -Horn sets, but we eliminated that restriction when we realized that it -can be useful for non-Horn sets. However, its use has been well analyzed -for non-Horn sets. - -``` my_option -set(restrict_denials). -clear(restrict_denials). % default clear -``` - -> If the flag is set, negative clauses (clauses in which all literals -> are negative) are referred to as *restricted denials* and are given -> special treatment. -> -> The inference rules (i.e., paramodulation and the resolution rules) -> will not be applied to restricted denials. However, restricted denials -> will be simplified by [back demodulation](glossary.html#demodulation) -> and [back unit deletion](glossary.html#unit-deletion). -> -> In addition, restricted denials will not be deleted if they are over -> the weight limit ([**`max_weight`**](process-inf.html#max_weight)). -> -> The effect of setting -> [**`restrict_denials`**](goals.html#restrict_denials) is that proofs -> will usually be more forward or direct. This option can speed up -> proofs, it can delay proofs, and it can block all proofs. - -## An Example - -The following example illustrates multiple goals (including a goal that -is a combination of other goals), -[**`auto_denials`**](goals.html#auto_denials), and -[**`restrict_denials`**](goals.html#restrict_denials). - -``` my_job -prover9 -f olsax.in > olsax.out -``` - ------------------------------------------------------------------------- - -Next Section: [Production Mode](production.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Prover9 Options - -There are three kinds of options: - -- *Flags* are Boolean-valued options which can be changed with the *set* - and *clear* commands, e.g., - `set(clocks)`. - `set(print_given)`. -- *Parms* are integer-valued options which can be changed with the - *assign* command, e.g., - `assign(max_weight, 30)`. -- *Stringparms* are string-valued options which can be changed with the - *assign* command, e.g., - `assign(order, kbo)`. - -## Option Dependencies - -Several of the flags and parameters cause other flags and parameters to -be changed. In some cases, that is the only direct effect they have. For -example, if you `clear(auto)`, you will see the following in the output. - -``` my_file -clear(auto). - % clear(auto) -> clear(auto_inference). - % clear(auto_inference) -> clear(predicate_elim). - % clear(auto_inference) -> assign(eq_defs, pass). - % clear(auto) -> clear(auto_limits). - % clear(auto_limits) -> assign(max_weight, 2147483647). - % clear(auto_limits) -> assign(sos_limit, -1). -``` - -The lines starting with "`%`" are the dependent options that are changed -in behalf of `clear(auto)`. Note the sub-dependencies in this example. - -The option dependencies can be undone by simply changing the dependent -option afterward, as in the following example input. - -``` my_file -clear(auto). -set(predicate_elim). -``` - -## Option Listing - -The option names below are links to the sections containing the -descriptions. - -### From Page [Clauses and Formulas](syntax.html) - -``` my_option -set(prolog_style_variables). -clear(prolog_style_variables). % default clear -``` - -### From Page [Automatic Modes](auto.html) - -``` my_option -set(auto). % default set -clear(auto). -``` - -``` my_option -set(auto_inference). % default set -clear(auto_inference). -``` - -``` my_option -set(auto_process). % default set -clear(auto_process). -``` - -``` my_option -set(auto_setup). % default set -clear(auto_setup). -``` - -``` my_option -set(auto_limits). % default set -clear(auto_limits). -``` - -``` my_option -set(auto2). -clear(auto2). % default clear -``` - -``` my_option -assign(lrs_ticks, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(lrs_interval, n). % default n=50, range [1 .. INT_MAX] -``` - -``` my_option -assign(min_sos_limit, n). % default n=0, range [0 .. INT_MAX] -``` - -``` my_option -set(raw). -clear(raw). % default clear -``` - -### From Page [Term Ordering](term-order.html) - -``` my_option -assign(order, string). % default string=lpo, range [lpo,rpo,kbo] -``` - -``` my_option -set(inverse_order). % default set -clear(inverse_order). -``` - -``` my_option -assign(eq_defs, string). % default string=unfold, range [unfold,fold,pass] -``` - -### From Page [More Search Prep](more-prep.html) - -``` my_option -set(expand_relational_defs). -clear(expand_relational_defs). % default clear -``` - -``` my_option -set(predicate_elim). % default set -clear(predicate_elim). -``` - -``` my_option -assign(fold_denial_max, n). % default n=0, range [-1 .. INT_MAX] -``` - -``` my_option -set(sort_initial_sos). -clear(sort_initial_sos). % default clear -``` - -``` my_option -set(process_initial_sos). % default set -clear(process_initial_sos). -``` - -### From Page [Search Limits](limits.html) - -``` my_option -assign(sos_limit, n). % default n=20000, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_given, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_kept, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_megs, n). % default n=200, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_seconds, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_minutes, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_hours, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_days, n). % default n=-1, range [-1 .. INT_MAX] -``` - -### From Page [Selecting the Given Clause](select.html) - -``` my_option -assign(age_part, n). % default n=1, range [0 .. INT_MAX] -``` - -``` my_option -assign(weight_part, n). % default n=0, range [0 .. INT_MAX] -``` - -``` my_option -assign(false_part, n). % default n=4, range [0 .. INT_MAX] -``` - -``` my_option -assign(true_part, n). % default n=4, range [0 .. INT_MAX] -``` - -``` my_option -assign(random_part, n). % default n=0, range [0 .. INT_MAX] -``` - -``` my_option -assign(hints_part, n). % default n=INT_MAX, range [0 .. INT_MAX] -``` - -``` my_option -set(default_parts). % default set -clear(default_parts). -``` - -``` my_option -assign(pick_given_ratio, n). % default n=0, range [0 .. INT_MAX] -``` - -``` my_option -set(lightest_first). -clear(lightest_first). % default clear -``` - -``` my_option -set(breadth_first). -clear(breadth_first). % default clear -``` - -``` my_option -set(random_given). -clear(random_given). % default clear -``` - -``` my_option -assign(random_seed, n). % default n=0, range [-1 .. INT_MAX] -``` - -``` my_option -set(input_sos_first). % default set -clear(input_sos_first). -``` - -### From Page [Inference Rules](inf-rules.html) - -``` my_option -set(binary_resolution). -clear(binary_resolution). % default clear -``` - -``` my_option -set(neg_binary_resolution). -clear(neg_binary_resolution). % default clear -``` - -``` my_option -set(ordered_res). % default set -clear(ordered_res). -``` - -``` my_option -set(check_res_instances). -clear(check_res_instances). % default clear -``` - -``` my_option -assign(literal_selection, string). % default string=max_negative, range [max_negative, all_negative, none] -``` - -``` my_option -set(pos_hyper_resolution). -clear(pos_hyper_resolution). % default clear -``` - -``` my_option -set(hyper_resolution). -clear(hyper_resolution). % default clear -``` - -``` my_option -set(neg_hyper_resolution). -clear(neg_hyper_resolution). % default clear -``` - -``` my_option -set(ur_resolution). -clear(ur_resolution). % default clear -``` - -``` my_option -set(pos_ur_resolution). -clear(pos_ur_resolution). % default clear -``` - -``` my_option -set(neg_ur_resolution). -clear(neg_ur_resolution). % default clear -``` - -``` my_option -set(initial_nuclei). -clear(initial_nuclei). % default clear -``` - -``` my_option -assign(ur_nucleus_limit, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -set(paramodulation). -clear(paramodulation). % default clear -``` - -``` my_option -set(ordered_para). % default set -clear(ordered_para). -``` - -``` my_option -set(check_para_instances). -clear(check_para_instances). % default clear -``` - -``` my_option -set(para_from_vars). % default set -clear(para_from_vars). -``` - -``` my_option -assign(para_lit_limit, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -set(para_units_only). -clear(para_units_only). % default clear -``` - -``` my_option -set(basic_paramodulation). -clear(basic_paramodulation). % default clear -``` - -### From Page [Processing Inferred Clauses](process-inf.html) - -``` my_option -set(lex_order_vars). -clear(lex_order_vars). % default clear -``` - -``` my_option -assign(demod_step_limit, n). % default n=1000, range [-1 .. INT_MAX] -``` - -``` my_option -assign(demod_increase_limit, n). % default n=1000, range [-1 .. INT_MAX] -``` - -``` my_option -set(back_demod). % default set -clear(back_demod). -``` - -``` my_option -set(lex_dep_demod). % default set -clear(lex_dep_demod). -``` - -``` my_option -assign(lex_dep_demod_lim, n). % default n=11, range [-1 .. INT_MAX] -``` - -``` my_option -set(lex_dep_demod_sane). % default set -clear(lex_dep_demod_sane). -``` - -``` my_option -set(unit_deletion). -clear(unit_deletion). % default clear -``` - -``` my_option -set(cac_redundancy). % default set -clear(cac_redundancy). -``` - -``` my_option -assign(max_literals, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_depth, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_vars, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(max_weight, n). % default n=100, range [INT_MIN .. INT_MAX] -``` - -``` my_option -set(safe_unit_conflict). -clear(safe_unit_conflict). % default clear -``` - -``` my_option -set(factor). -clear(factor). % default clear -``` - -``` my_option -assign(new_constants, n). % default n=0, range [-1 .. INT_MAX] -``` - -``` my_option -set(back_subsume). % default set -clear(back_subsume). -``` - -``` my_option -assign(backsub_check, n). % default n=500, range [-1 .. INT_MAX] -``` - -### From Page [Output Files](output.html) - -``` my_option -set(echo_input). % default set -clear(echo_input). -``` - -``` my_option -set(quiet). -clear(quiet). % default clear -``` - -``` my_option -set(print_initial_clauses). % default set -clear(print_initial_clauses). -``` - -``` my_option -set(print_given). % default set -clear(print_given). -``` - -``` my_option -set(print_gen). -clear(print_gen). % default clear -``` - -``` my_option -set(print_kept). -clear(print_kept). % default clear -``` - -``` my_option -set(print_labeled). -clear(print_labeled). % default clear -``` - -``` my_option -set(print_clause_properties). -clear(print_clause_properties). % default clear -``` - -``` my_option -set(print_proofs). % default set -clear(print_proofs). -``` - -``` my_option -set(default_output). % default set -clear(default_output). -``` - -``` my_option -assign(report, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(stats, string). % default string=lots, range [none,some,lots,all] -``` - -``` my_option -set(clocks). -clear(clocks). % default clear -``` - -``` my_option -set(bell). % default set -clear(bell). -``` - -### From Page [Weighting](weight.html) - -``` my_option -assign(constant_weight, n). % default n=1, range [INT_MIN .. INT_MAX] -``` - -``` my_option -assign(sk_constant_weight, n). % default n=1, range [INT_MIN .. INT_MAX] -``` - -``` my_option -assign(variable_weight, n). % default n=1, range [INT_MIN .. INT_MAX] -``` - -``` my_option -assign(not_weight, n). % default n=0, range [INT_MIN .. INT_MAX] -``` - -``` my_option -assign(or_weight, n). % default n=0, range [INT_MIN .. INT_MAX] -``` - -``` my_option -assign(prop_atom_weight, n). % default n=1, range [INT_MIN .. INT_MAX] -``` - -``` my_option -assign(nest_penalty, n). % default n=0, range [0 .. INT_MAX] -``` - -``` my_option -assign(depth_penalty, n). % default n=0, range [INT_MIN .. INT_MAX] -``` - -``` my_option -assign(var_penalty, n). % default n=0, range [INT_MIN .. INT_MAX] -``` - -``` my_option -assign(default_weight, n). % default n=INT_MAX, range [INT_MIN .. INT_MAX] -``` - -### From Page [Goals and Denials](goals.html) - -``` my_option -assign(max_proofs, n). % default n=1, range [-1 .. INT_MAX] -``` - -``` my_option -set(reuse_denials). -clear(reuse_denials). % default clear -``` - -``` my_option -set(auto_denials). % default set -clear(auto_denials). -``` - -``` my_option -set(restrict_denials). -clear(restrict_denials). % default clear -``` - -### From Page [Hints](hints.html) - -``` my_option -set(breadth_first_hints). -clear(breadth_first_hints). % default clear -``` - -``` my_option -set(degrade_hints). % default set -clear(degrade_hints). -``` - -``` my_option -set(limit_hint_matchers). -clear(limit_hint_matchers). % default clear -``` - -``` my_option -set(back_demod_hints). % default set -clear(back_demod_hints). -``` - -``` my_option -set(collect_hint_labels). -clear(collect_hint_labels). % default clear -``` - -### From Page [Semantic Guidance](semantics.html) - -``` my_option -assign(multiple_interps, string). % default string=false_in_all, range [false_in_all, false_in_some] -``` - -``` my_option -assign(eval_limit, n). % default n=1024, range [-1 .. INT_MAX] -``` - ------------------------------------------------------------------------- - -Next Section: [Glossary](glossary.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Automatic Modes - -> Prover9's automatic mode is set by default. Otter's automatic mode -> must be explicitly set. - -If you simply give Prover9 a set of clauses and/or formulas, Prover9 -will look at the clauses and decide which inference rules and -clause-processing operations to use. If you don't like the automatic -decisions that Prover9 makes, you can clear the flag -[**`auto`**](auto.html#auto) or any of the secondary auto flags that -depend on it. Prover9 output files show in detail the effects of -changing these flags. - -``` my_option -set(auto). % default set -clear(auto). -``` - -> This is the basic automatic mode of Prover9. The only direct effect of -> this flag is that it changes four secondary auto flags as follows. -> -> set(auto) -> set(auto_inference). -> set(auto) -> set(auto_process). -> set(auto) -> set(auto_setup). -> set(auto) -> set(auto_limits). -> set(auto) -> set(auto_denials). -> -> clear(auto) -> clear(auto_inference). -> clear(auto) -> clear(auto_process). -> clear(auto) -> clear(auto_setup). -> clear(auto) -> clear(auto_limits). -> clear(auto) -> clear(auto_denials). -> -> Any of the secondary flags, as well as the entire automatic mode can -> be cleared by the user. - -``` my_option -set(auto_inference). % default set -clear(auto_inference). -``` - -> If this flag is set, the input clauses are checked for several -> syntactic properties such as the presence of equality and -> [non-Horn](glossary.html#horn) clauses. Based on the results of the -> checks, Prover9 decides which inference rules to use. -> -> Unlike ordinary option dependencies, the options that are changed by -> [**`auto_inference`**](auto.html#auto_inference) cannot be undone by -> placing commands in the input file, because they depend on the -> structure of the clauses. - -``` my_option -set(auto_process). % default set -clear(auto_process). -``` - -> This flag causes several other flags that affect clause processing to -> be altered based syntactic properties of the initial clauses. -> -> If all clauses are Horn and there are negative nonunits, the flag -> [**`back_unit_deletion`**](process-inf.html#back_unit_deletion) is -> automatically set. If there are non-Horn clauses, the flags -> [**`back_unit_deletion`**](process-inf.html#back_unit_deletion) and -> [**`factor`**](process-inf.html#factor) are automatically set. -> -> Unlike ordinary option dependencies, the options that are changed by -> [**`auto_process`**](auto.html#auto_process) cannot be undone by -> placing commands in the input file, because they depend on the -> structure of the clauses. - -``` my_option -set(auto_setup). % default set -clear(auto_setup). -``` - -> The only effect of changing this flag is that two parameters are -> changed in the following ways. -> -> set(auto_setup) -> set(predicate_elim). -> set(auto_setup) -> assign(eq_defs, unfold). -> -> clear(auto_setup) -> clear(predicate_elim). -> clear(auto_setup) -> assign(eq_defs, pass). - -``` my_option -set(auto_limits). % default set -clear(auto_limits). -``` - -> The only effect of changing this flag is that two parameters are -> changed in the following ways. -> -> set(auto_limits) -> assign(max_weight, 100). -> set(auto_limits) -> assign(sos_limit, 10000). -> -> clear(auto_limits) -> assign(max_weight, INT_MAX). -> clear(auto_limits) -> assign(sos_limit, -1). - -## An Experimental Automatic Mode - -``` my_option -set(auto2). -clear(auto2). % default clear -``` - -> This is an enhanced automatic mode, developed in preparation for -> CASC-2005. The only direct effect of changing this option is that it -> causes several other options to be changed. See an output file to see -> the effects of setting this flag. - -## Automatically Adjusting the [**`sos_limit`**](limits.html#sos_limit) Parameter - -``` my_option -assign(lrs_ticks, n). % default n=-1, range [-1 .. INT_MAX] -``` - -``` my_option -assign(lrs_interval, n). % default n=50, range [1 .. INT_MAX] -``` - -``` my_option -assign(min_sos_limit, n). % default n=0, range [0 .. INT_MAX] -``` - -> These three parameters work together and are used to automatically -> adjust the parameter [**`sos_limit`**](limits.html#sos_limit) by means -> of a "limited resource strategy" \[[RV-lrs](references.html#RV-lrs)\]. -> If [**`lrs_ticks`**](auto.html#lrs_ticks) ≥ 0, the method is applied. -> -> This is an experimental feature and is not recommended for general -> use. - -## Raw Mode - -The default values of the options can interfere with specialized search -strategies. To avoid some of those problems, one can start from scratch -by setting the following option. - -``` my_option -set(raw). -clear(raw). % default clear -``` - -> This is a sort of anti-automatic mode, which allows the user to -> completely specify the search strategy, with less chance of -> interference from the default settings of various options. For -> example, to generate all binary resolvents, one can simply set the -> flags `raw` and -> [**`binary_resolution`**](inf-rules.html#binary_resolution) instead of -> finding and clearing the flags that restrict resolution. -> -> The flag works by making the following changes. -> -> set(raw) -> clear(auto). -> clear(auto) -> clear(auto_inference). -> clear(auto) -> clear(auto_setup). -> clear(auto_setup) -> clear(predicate_elim). -> clear(auto_setup) -> assign(eq_defs, pass). -> clear(auto) -> clear(auto_limits). -> clear(auto_limits) -> assign(max_weight, 2147483647). -> clear(auto_limits) -> assign(sos_limit, -1). -> clear(auto) -> clear(auto_denials). -> clear(auto) -> clear(auto_process). -> set(raw) -> clear(ordered_res). -> set(raw) -> clear(ordered_para). -> set(raw) -> assign(literal_selection, none). -> set(raw) -> clear(back_demod). -> set(raw) -> clear(cac_redundancy). -> set(raw) -> assign(backsub_check, 2147483647). -> set(raw) -> set(lightest_first). -> set(lightest_first) -> assign(weight_part, 1). -> set(lightest_first) -> assign(age_part, 0). -> set(lightest_first) -> assign(false_part, 0). -> set(lightest_first) -> assign(true_part, 0). -> set(lightest_first) -> assign(random_part, 0). - ------------------------------------------------------------------------- - -Next Section: [Term Ordering](term-order.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Output Files - -Even when Prover9 fails to find a proof, its output file usually has -lots of valuable information about the search. The output file can -suggest many ways of improving the search for subsequent jobs as in the -following examples. - -- The output shows how equalities are oriented; different [term ordering - parameters](term-order.html) may give better or more intuitive - orientations. -- If Prover9 focused the search on uninteresting clauses (see the - sequence of given clauses), different [inference - rules](inf-rules.html), a different - [**`pick_given_ratio`**](select.html#pick_given_ratio), or a - specialized [weighting function](weight.html) can be used. -- If Prover9 ran out of time or memory with a huge `sos` list and small - `usable` list (i.e., few given clauses were used), the - [**`sos_limit`**](limits.html#sos_limit) should be reduced. - -## Basic Structure of Output Files - -Prover9 output files are divided into sections and subsections so the -users (people and programs) can find what they are looking for. The -delimiters are self-explanatory. A few comments about the sections are -given here. For a specific example, see the output file -[subset_trans.out](subset_trans.out). - -``` my_file -============================== Prover9 =============================== - Version, date, host computer, command. -============================== end of head =========================== - -============================== INPUT ================================= - Echo of the input. Everything in this section that is not - in the input is commented with "%", so copy-and-paste can be - done on this section to create a new input file. -============================== end of input ========================== - -============================== PROCESS GOALS ========================= - The search is always by refutation, and this section shows - how goals are negated in preparation for the search. -============================== end of process goals ================== - -============================== PROCESS INITIAL CLAUSES =============== - This section shows the starting clauses (after Skomemization, - if applicable) and then some of what Prover9 does in preparation - for the search. This includes predicate_elim, term ordering - decisions, and auto_inference settings. At this stage, clauses - may be deleted by subsumption and equations may be copied to the - list demodulators. See the flag process_initial_sos. -============================== end of process initial clauses ======== - -============================== CLAUSES FOR SEARCH ==================== - This section shows the clauses just before the start of the - search, that is, just before selection of the first given clause. - -============================== end of clauses for search ============= - -============================== SEARCH ================================ - This section typically shows the sequence of given clauses, - and it may also include PROOF and STATISTICS sections. - -============================== PROOF ================================= - A proof in standard form. -============================== end of proof ========================== - -============================== STATISTICS ============================ - We encourage users to look at statistics! -============================== end of statistics ===================== - -============================== end of search ========================= -``` - -## Clause Justifications - -After the initial stage of the output, each clause in the file has an -integer identifier (ID) and a justification that may refer to IDs of -other clauses. A justification is a list consisting of one primary step -and some number of secondary steps. Most primary steps are inference -rules applied to given clauses, and most secondary steps consist of -simplification, rewriting, or orienting equalities. - -Many of the types of step refer to positions of literals or terms in the -parent clauses. Literals are identified by the characters 'a' (first -literal), 'b' (second literal), etc. Terms are identified by the literal -identifier followed by a sequence of integers giving the position of the -term within the literal. For example, the position 'c,1,3,2' means third -literal, first argument, third argument, second argument. Negation signs -on literals are not included in the sequence. - -Primary Steps. - -- `assumption` -- input formula. -- `clausify` -- from CNF translation of a non-clausal assumption. -- `goal` -- input formula. -- `deny` -- from CNF translation of the negation of a goal. -- `resolve(59,b,47,c)` -- resolve the second literal of clause 59 with - the third literal of clause 47. -- `hyper(59, b,47,a, c,38,a)` -- hyperresolution; interpret the list as - a clause ID followed by a sequence of triples, - \ the inference is presented as a sequence - of binary resolution steps. In the example shown, start with clause - 59; then resolve literal b with clause 47 on literal a; with the - result of the first step, resolve literal c with clause 38 on - literal a. The special case "`xx`" means resolution with `x=x`. -- `ur(39, a,48,a, b,88,a, c,87,a, d,86,a)` -- unit-resulting resolution; - the list is interpreted as in hyperresolution. -- `para(47(a,1),28(a,1,2,2,1))` -- paramodulate from the clause 47 into - clause 28 at the positions shown. -- `copy(59)` -- copy clause 59. -- `back_rewite(59)` -- copy clause 59. -- `back_unit_del(59)` -- copy clause 59. -- `new_symbol(59)` -- introduce a new constant (see parameter - [**`new_constants`**](inf-rules.html#new_constants)). -- `factor(59,b,c)` -- factor clause 59 by unifying the second and third - literals. -- `xx_res(59,b)` -- resolve the second literal of clause 59 with `x=x`. -- `propositional` -- not used in standard proofs. -- `instantiate` -- not used in standard proofs. -- `ivy` -- not used in standard proofs. - -Secondary Steps (each assumes a working clause, which is either the -result of a primary step or a previous secondary step). - -- `rewrite([38(5,R),47(5),59(6,R)])` -- rewriting (demodulation) with - equations 38, 47, then 59; the arguments (5), (5), and (6) identify - the positions of the rewritten subterms (in an obscure way), and the - argument R indicates that the demodulator is used backward - (right-to-left). -- `flip(c)` -- the third literal is an equality that has been flipped by - the term ordering. This does not necessarily mean that the equality is - orientable by the primary term ordering, e.g., KBO. -- `merge(d)` -- the fourth literal has been removed because it was - identical to a preceding literal. -- `unit_del(b,38)` -- the second literal has been removed because it was - an instance of the negation clause 38 (which is a unit clause). -- `xx(b)` -- the second literal has been removed because it was an - instance of `x!=x`. - -## Standard Proofs - -Prover9 proofs may be transformed by separate programs, e.g., by -[Prooftrans](prooftrans.html). - -## Options That Say What Goes To the Output File - -``` my_option -set(echo_input). % default set -clear(echo_input). -``` - -> Clearing this flag suppresses printing of clauses, formulas, weighting -> rules (and everything else that ends with `end_of_list`) that would -> ordinarily appear in the `INPUT` section of the output file. - -``` my_option -set(quiet). -clear(quiet). % default clear -``` - -> Setting this flag causes most messages to the standard error file -> (usually the user's screen) to be suppressed. These messages include -> notifications about proofs and statistics reports, and warnings about -> demodulation limits. Setting this flag also suppresses several -> messages to the ordinary output file, and it clears the -> [**`bell`**](output.html#bell) flag. - -``` my_option -set(print_initial_clauses). % default set -clear(print_initial_clauses). -``` - -> If this flag is set, clauses are printed in the -> `PROCESS INITIAL CLAUSES` and `CLAUSES FOR SEARCH` sections of the -> output file. - -``` my_option -set(print_given). % default set -clear(print_given). -``` - -> Clearing this flag prevents given clauses from being printed to the -> output file. - -``` my_option -set(print_gen). -clear(print_gen). % default clear -``` - -> Setting this flag causes all generated clauses to be printed to the -> the output file. In addition, some other information about the -> processing of each generated clause is printed. This flag can be -> output files to be really huge. - -``` my_option -set(print_kept). -clear(print_kept). % default clear -``` - -> Setting this flag causes all kept clauses to be printed to the the -> output file. In addition, some other information on the processing of -> kept clauses is printed. - -``` my_option -set(print_labeled). -clear(print_labeled). % default clear -``` - -> Setting this flag causes kept clauses containing label attributes to -> be printed, even when the flag -> [**`print_kept`**](output.html#print_kept) is clear. This flag is -> useful when using [the hints strategy](hints.html), because when a -> clause matches a hint containing a label, the label is copied to the -> clause. That is, clauses matching labeled hints will be printed. - -``` my_option -set(print_clause_properties). -clear(print_clause_properties). % default clear -``` - -> Setting this flag causes several properties of clauses to be printed -> as "props" attributes on the clauses. The properties include which -> literals are maximal (counting from 1), which literals are maximal -> among literals of the same sign, and which literals are selected for -> application of inference rules. - -``` my_option -set(print_proofs). % default set -clear(print_proofs). -``` - -> Clearing this flag prevents proofs from being printed to the output -> file. The proof message still goes to the standard error file (usually -> the user's screen), unless the flag [**`quiet`**](output.html#quiet) -> has been set. - -``` my_option -set(default_output). % default set -clear(default_output). -``` - -> Setting this flag restores most of the output flags and parameters to -> their default values. Clearing this flag does nothing. - -``` my_option -assign(report, n). % default n=-1, range [-1 .. INT_MAX] -``` - -> If *n* \> 0, statistics are sent to the output file approximately -> every *n* seconds. (On Unix-like systems, one can also tell Prover9 to -> print statistics to the output file by sending the signal `USR1` to a -> running Prover9 process, e.g., `kill -USR1 4223`.) - -``` my_option -assign(stats, string). % default string=lots, range [none,some,lots,all] -``` - -> This parameter determines how many statistics are sent to the output -> file. - -``` my_option -set(clocks). -clear(clocks). % default clear -``` - -> If this flag is set, various operations during the Prover9 job are -> timed (e.g., inference, demodulation, and subsumption), and timing -> reports are sent to the output file. -> -> Timing the operations can be expensive, especially in Solaris and -> Macintosh systems. On Linux systems, `set(clocks)` typically adds 5% -> -- 10% to the run time. - -``` my_option -set(bell). % default set -clear(bell). -``` - -> If this flag is set, Prover9 beeps when important things happen, such -> as proofs and warnings. Some users run searches that find hundreds of -> proofs, and they clear this flag to prevent all of the beeping. - ------------------------------------------------------------------------- - -Next Section: [Weighting](weight.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Mace4 (Models And CounterExamples) - -The program [Mace4](http://www.cs.unm.edu/~mccune/mace4/) -\[[McCune-Mace4](references.html#McCune-Mace4)\] searches for finite -structures satisfying first-order and equational statements (the same -kind of statement that Prover9 accepts). If the statement is the denial -of some conjecture, any structures found by Mace4 are counterexamples to -the conjecture. - -Mace4 can be a valuable complement to Prover9, looking for -counterexamples before (or at the same time as) using Prover9 to search -for a proof. It can also be used to help debug input clauses and -formulas for Prover9. - -For the most part, Mace4 accepts the same input files as Prover9. If the -input file contains commands that Mace4 does not understand, then the -argument "-c" must be given to tell Mace4 to ignore those commands. - -For example, say we're learning group theory, and we're wondering -whether all groups are commutative. We can run the following two jobs in -parallel, with Prover9 looking for a proof, and Mace4 looking for a -counterexample. - -``` my_job -prover9 -f x2.in > x2.prover9.out -mace4 -c -f x2.in > x2.mace4.out -``` - -Most of the options accepted by Mace4 can be given either on the command -line or in the input file. The following command lists the command-line -options accepted by Mace4. - -``` my_job -mace4 -help -``` - -**Terminology**. We use the terms *interpretation*, *model*, and -*structure* for the objects that Mace4 produces. From a logic point of -view, Mace4 produces interpretations which are models of the input -formulas. From a math point of view, Mace4 produces structures -satisfying the input formulas. - -## What Mace4 Does - -Mace4 searches for *unsorted finite structures* only. That is, a -structure (model) has one underlying finite set, called the *domain* -(the members are always 0,1,...,*n-1* for a set of size *n*), and -structures are functions and relations (tables) over the domain, -corresponding to the operations and relation symbols in the -specification. - -By default, Mace4 starts searching for a structure of domain size 2, and -then it increments the size until it succeeds or reaches some limit. - -## The Original Mace4 Manual - -The original Mace4 manual -\[[McCune-Mace4](references.html#McCune-Mace4)\] -([PDF)](http://www.cs.unm.edu/~mccune/prover9/mace4.pdf) is out of date -with respect to features and options, but it contains useful information -on the history of Mace4, details on the search methods, and the -differences between Mace2 and Mace4. - ------------------------------------------------------------------------- - -Next Section: [Mace4 Input](m4-input.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Mace4 Input - -Mace4 has been designed so that it accepts most Prover9 input files. -This allows users to prepare one input file which can be used by Prover9 -(to search for proofs) and by Mace4 (to search for counterexamples). - -## Mace4 Options - -Mace4 and Prover9 accept different sets of flags and parameters. In -order to use the same input files for both programs, we let Mace4 take -its options from the command line instead of from the input file. If -Mace4 is given a Prover9 input file, along with the command-line option -`-c`, it will ignore any unrecognized (e.g., Prover9) options in the -input file. The Mace4 options are described on the [next -page](m4-options.html). - -## Formulas (including Clauses) - -Mace4 accepts the same formulas and clauses as Prover9. See the page -[Prover9 Clauses and Formulas](syntax.html). - -### *A Caveat: Domain Elements* - -> In one important case, formulas have different meanings in Prover9 and -> Mace4: - -If a formula contains constants that are natural-numbers, {0,1,...}, -Mace4 assumes they are members of the domain of some structure, that is, -they are distinct objects; in effect, Mace4 operates under the -assumptions 0 ≠ 1, 0 ≠ 2, ... . - -To Prover9, natural numbers are just ordinary constants. For example, to -Prover9 the statement 0=1 is satisfiable, and to Mace4 it is -unsatisfiable. - -Because Mace4 assumes that natural-number constants are members of the -domain, if a formula contains a natural number that is out of range (≥ -*n*), when searching for a structure of size *n*), Mace4 will terminate -its search for size *n* (and continue with larger sizes if the -specification says to do so). - -*An Exception.* When the flag `arithmetic` is set, natural numbers -outside of {0,1,...,n-1} can occur. - -## Lists of Formulas (including Clauses) - -Prover9 accepts a fixed set of lists of formulas (e.g., `assumptions`, -`usable`, `goals`, `hints`). - -Mace4 accepts any lists of formulas. All are treated as ordinary -formulas *except the following two lists*. - -- `formulas(hints)`. These are intended to help Prover9 find proofs and - are ignored by Mace4. -- `formulas(goals)`. These are negated by Mace4, just as they are by - Prover9. - -### `formulas(goals)` - -Prover9 has several restrictions on the goals it accepts (see [Prover9 -Goals and Denials](goals.html)), and Mace4 has the same restrictions. -Mace4 negates goals and translates them to clauses in the same way as -Prover9. (The term "goal" might seem to be bad teminology for Mace4 -users, because Mace4 does not prove theorems; however, one can think of -Mace4 as searching for a counterexample to the goal.) - -When there are multiple goals, Mace handles them the same as Prover9. -For example, consider the following goals. - -``` my_file -formulas(goals). - x * y = y * x # label(commutativity). - (x * y) * z = x * (y * z) # label(associativity). -end_of_list. -``` - -Logically, this is a disjunction: Prover9 gives a proof if either goal -is proved, and Mace4 gives a counterexample if both are falsified. In -particular, this pair of goals is equivalent (for both Prover9 and -Mace4) to the following pair of assumptions. - -``` my_file -formulas(assumptions). - exists x exists y (x * y != y * x). - exists x exists y exists z (x * y) * z != x * (y * z). -end_of_list. -``` - -## Distinct Objects - -Mace4 accepts a shorthand method for stating that sets of objects are -distinct. Here is an example of two sets of distinct objects. - -``` my_file -list(distinct). -[a,b,c]. % equivalent to (a!=b & a!=c & b!=c). -[d,e,f(a)]. % equivalent to (d!=e & d!=f(a) & e!=f(a)). -end_of_list. -``` - -Although `list(distinct)` will probably be used mostly for constants and -other ground terms, terms with variables can occur. - ------------------------------------------------------------------------- - -Next Section: [Mace4 Options](m4-options.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Mace4 Options - -Mace4 accepts `set`, `clear`, and `assign` commands in the input file. -Several of these are in common with Prover9 (e.g., -`assign(max_seconds, 30)`), but most are specifically for Mace4. - -If Mace4 is called with the command-line option `-c` (compatability -mode), it will ignore any `set`, `clear`, and `assign` that it does not -recognize, assuming they are meant for some other program (Prover9). - -Most Mace4 options can be specified on the command line instead of in -the input file. When Mace4 options are specified on the command line, -single-character codes are used. For example, the command-line option -`-t 30` means the same as `assign(max_second, 30)` in the input file. If -an option is given in *both* places, the one on the command line takes -precedence. Command-line options for Boolean-valued options (flags) -always take an argument: 1 means "set", and 0 means "clear". For -example, `-V 1` means `set(prolog_style_vaiables`, and `-V 0` means -`clear(prolog_style_variables)`. - -The command "`mace4 -help`" shows the correspondence between the -command-line codes and the option names, and it shows the default -values. - -## Symbol Ordering - -Like Prover9, Mace4 accepts `function_order` and `relation_order` -commands that specify an order on the symbols in the problem. The syntax -of the commands is the [same as in -Prover9](term-order.html#lex_command), for example, - -``` my_file -predicate_order([=, <=, P, Q]). % = < P < Q -function_order([a, b, c, +, *, h, g]). % a < b < c < + < * < h < g -``` - -Mace4's the default symbol order is the [same as -Prover9's](term-order.html#default_lex). As in Prover9, function symbols -are always less than predicate symbols. - -The symbol order can have a big effect on the time it takes to find a -model or exhaust a domain size, because it determines the order in which -Mace4 tries to fill in the function and relation tables. Unfortunately, -we do not know of any general-purpose heuristics for selecting a good -symbol order. If Mace4 takes too long to go through a particular domain -size, we suggest trying a different symbol order. - -## Option Listing - -### Basic Options - -``` my_file -assign(start_size, n). % default n=2, range [2 .. INT_MAX] % command-line -n n -``` - -``` my_file -assign(end_size, n). % default n=-1, range [-1 .. INT_MAX] % command-line -N n -``` - -``` my_file -assign(increment, n). % default n=1, range [1 .. INT_MAX] % command-line -i n -``` - -These three parameter work together to determine the domain sizes to be -searched. The search starts for structures of size `start_size`; if that -search fails, the size is incremented, and another search starts. This -continues up through the value `end_size` (or until some other limit -terminates the process). If `end_size` is -1, there is no limit. (Also -see the `iterate` parameter below.) - -For example, the command-line options "`-n 5 -N 11 -i 2`" say to try -domain sizes 5,7,9,11. - -``` my_file -assign(domain_size, n). % default n=0, range [0 .. INT_MAX] % command-line -n n -``` - -This parameter says to search *only* the given size. This (meta-) -parameter works simply by making the following changes. - - assign(domain_size, n) -> assign(start_size, n). - assign(domain_size, n) -> assign(end_size, n). - -``` my_file -assign(iterate, string). % default string=all, range [all,evens,odds,primes,nonprimes] -``` - -The `iterate` parameter can be used to add an additional constraint to -the domain sizes. It can be used together with the `increment` -parameter. The `iterate` parameter cannot be specified on the command -line. - -``` my_file -assign(max_models, n). % default n=1, range [-1 .. INT_MAX] % command-line -m n -``` - -The parameter `max_models` says to stop searching when the *n*-th -structure has been found. A value of -1 means there is no limit. - -``` my_file -assign(max_seconds, n). % default n=-1, range [-1 .. INT_MAX] % command-line -t n -``` - -The parameter [**`max_seconds`**](limits.html#max_seconds) says to stop -searching after *n* seconds. A value of -1 means there is no limit. - -``` my_file -assign(max_seconds_per, n). % default n=-1, range [-1 .. INT_MAX] % command-line -s n -``` - -The parameter allows at most *n* seconds for each domain size. The -parameter [**`max_seconds`**](limits.html#max_seconds) can be used -(together with `max_seconds_per`) to given an overall time limit. A -value of -1 means there is no limit. - -``` my_file -assign(max_megs, n). % default n=200, range [-1 .. INT_MAX] % command-line -b n -``` - -The parameter [**`max_megs`**](limits.html#max_megs) says to stop -searching when (about) *n* megabytes of memory have been used. A value -of -1 means there is no limit. - -``` my_file -set(prolog_style_variables). % command-line -V 1 -clear(prolog_style_variables). % default clear % command-line -V 0 -``` - -A rule is needed for distinguishing variables from constants in clauses -and formulas with free variables. If this flag is clear, variables start -with (lower case) 'u' through 'z'. If this flag is set, variables in -clauses start with (upper case) 'A' through 'Z' or '\_'. - -``` my_file -set(print_models). % default set % command-line -P 1 -clear(print_models). % command-line -P 0 -``` - -If this flag is set, all structures that are found are printed in -"standard" form, which means they are suitable as input to other LADR -programs such as [isofilter](m4-isofilter.html) and -[interpformat](m4-interpforma.html). - -``` my_file -set(print_models_tabular). % command-line -p 1 -clear(print_models_tabular). % default clear % command-line -p 0 -``` - -If this flag is set, and if is clear, all structures that are found are -printed in a tabular form. If both `print_models` and -`print_models_standard` are set, the last one in the input takes effect. - -``` my_file -set(integer_ring). % command-line -R 1 -clear(integer_ring). % default clear % command-line -R 0 -``` - -If this flag is set, a ring structure is is applied to the search. The -operations {+,-,\*} are assumed to be the ring of integers (mod -domain_size). This method puts a tight constraint on the search, -allowing much larger structures to be investigated. Here is an example. - -``` my_job -mace4 -f ring41.in > ring41.out -``` - -For further information on the `integer_ring` flag, see [slides from a -workshop -presentation](http://www.cs.unm.edu/~mccune/slides/award-2004.pdf). - -``` my_file -set(order_domain). -clear(order_domain). % default clear -``` - -If this flag is set, the relations `<` and `<=` are fixed as order -relations on the domain in the obvious way. - -``` my_file -set(arithmetic). -clear(arithmetic). % default clear -``` - -If this flag is set, several function and relation symbols understood by -Mace4 as operations and relations on the integers, and evaluation of -terms involving those symbols occurs during the search for models. See -the page [Arithmetic for Mace4](m4-arithmetic.html). - -``` my_file -set(verbose). % command-line -v 1 -clear(verbose). % default clear % command-line -v 0 -``` - -If the `verbose` flag is set, the output file receives information about -the search, including the initial partial model (the part of the model -that can be determined before backtracking starts) and timing and other -statistics for each domain size. (It does not give a trace of the -backtracking, so it does not consume a lot of file space.) - -``` my_file -set(trace). % command-line -T 1 -clear(trace). % default clear % command-line -T 0 -``` - -If the `trace` flag is set, detailed information about the search, -including a trace of all assignments and backtracking, is printed to the -standard output. *This flag causes a lot of output, so it should be used -only on small searches*. - -### Advanced Options - -These options are used for experimentation with search methods. They can -be ignored by nearly all users. For descriptions of most of these -options, see the original Mace4 manual -\[[McCune-Mace4](references.html#McCune-Mace4)\] -([PDF)](http://www.cs.unm.edu/~mccune/prover9/mace4.pdf). - -``` my_file -set(lnh). % default set % command-line -L 1 -clear(lnh). % command-line -L 0 -``` - -``` my_file -assign(selection_order, n). % default n=2, range [0 .. 2] % command-line -O n -``` - -``` my_file -assign(selection_measure, n). % default n=4, range [0 .. 4] % command-line -M n -``` - -``` my_file -set(negprop). % default set % command-line -G 1 -clear(negprop). % command-line -G 0 -``` - -``` my_file -set(neg_assign). % default set % command-line -H 1 -clear(neg_assign). % command-line -H 0 -``` - -``` my_file -set(neg_assign_near). % default set % command-line -I 1 -clear(neg_assign_near). % command-line -I 0 -``` - -``` my_file -set(neg_elim). % default set % command-line -J 1 -clear(neg_elim). % command-line -J 0 -``` - -``` my_file -set(neg_elim_near). % default set % command-line -K 1 -clear(neg_elim_near). % command-line -K 0 -``` - -``` my_file -set(skolems_last). % command-line -S 1 -clear(skolems_last). % default clear % command-line -S 0 -``` - ------------------------------------------------------------------------- - -Next Section: [Interpformat](m4-arithmetic.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Interpformat - -The models (structures) in Mace4 output files can be transformed in -various ways with the program Interpformat. - -The transformations are listed here. - -- `standard`: This transformation simply extracts the structure from the - file and reprints it in the same (standard) format, with one line for - each operation. The result should be acceptable to any of the LADR - programs that take standard structures. -- `standard2`: This is similar to `standard`, except that the binary - operations are split across multiple lines to make them more - human-readable. The result should be acceptable to any of the LADR - programs that take standard structures. -- `portable`: This form is list of ... of lists of strings and natural - numbers. It can be parsed by seveal scripting systems such as GAP, - Python, and Javascript. See the section [Portable Format](#portable). -- `tabular`: This form is designed to be easily readable by humans. It - is not meant for input to other programs. -- `raw`: This form is a sequence of natural numbers. -- `cooked`: This form is a sequence of ground terms. -- `xml`: This is an XML form. Here is a [DTD](interp3.dtd) for LADR - interpretations, and here is an [XML stylesheet](interp3.xsl) for - transforming the XML to HTML. -- `tex`: This generates LaTeX source for the interpretation. - -## Examples - -The following Mace4 job creates an output file containing one model in -"standard" (the default) format. - -``` my_job -mace4 -c -f x2.in > x2.mace4.out -``` - -The following Interpformat jobs take the Mace4 output file, extract the -model, and transform it as described above. - -``` my_job -interpformat standard -f x2.mace4.out > x2.standard -interpformat standard2 -f x2.mace4.out > x2.standard2 -interpformat portable -f x2.mace4.out > x2.portable -interpformat tabular -f x2.mace4.out > x2.tabular -interpformat raw -f x2.mace4.out > x2.raw -interpformat cooked -f x2.mace4.out > x2.cooked -interpformat xml -f x2.mace4.out > x2.xml -interpformat tex -f x2.mace4.out > x2.tex -``` - -Portable Format - -The portable format for interpretations can be parsed by several -scriping languages including [Python](http://www.python.org) and -[GAP](http://www.gap-system.org). Here is a counterexample on ternary -relations in lattice theory. The result contains one interpretation of -size 4 containing two binary functions (meet and join), one binary -relation (less-or-equal), two ternary relations, and three constants. - -``` my_job -mace4 -c -f LT-port.in | interpformat portable > LT-port.out -``` - -The result is a list of interpretations: - -- each interpretation is a triple: \[size-of-interpretation (say n), - comments, list-of-operations\]; -- each operation is a 4-tuple: \["function" \| "relation", - name-of-operation, arity, values\]; -- values of operations (domain elememts are \[0 ... n-1\]): - - constant (nullary function): domain element; - - unary function: list of domain elements; - - binary funcion: 2-dimensional list (list of lists) of domain - elements; - - ternary funcion: 3-dimensional list of domain elements; - - etc. - - relations are similar but with values of 0 (FALSE) or 1 (TRUE). - -Here is a simple Python script that reads a list of portable -interpretations and prints them in a different form. - -``` my_job -port.py < LT-port.out > LT-port.out2 -``` - -Here is a simple GAP session that reads and prints a list of portable -interpretations. - -``` my_screen -% gap -b -GAP4, Version: 4.4.7 of 17-Mar-2006, i486-pc-linux-gnu-i486-linux-gnu-gcc -gap> interpretations := EvalString(StringFile("LT-port.out"));; -gap> interpretations; -[ [ 4, [ "=(number,1)", "=(seconds,0)" ], - [ [ "relation", "<=", 2, [ [ 1, 1, 1, 1 ], [ 0, 1, 0, 0 ], - [ 0, 1, 1, 0 ], [ 0, 1, 0, 1 ] ] ], - [ "function", "^", 2, [ [ 0, 0, 0, 0 ], [ 0, 1, 2, 3 ], - [ 0, 2, 2, 0 ], [ 0, 3, 0, 3 ] ] ], - [ "function", "v", 2, [ [ 0, 1, 2, 3 ], [ 1, 1, 1, 1 ], - [ 2, 1, 2, 1 ], [ 3, 1, 1, 3 ] ] ], - [ "function", "c1", 0, 2 ], [ "function", "c2", 0, 0 ], - [ "function", "c3", 0, 3 ], - [ "relation", "A", 3, [ [ [ 1, 1, 1, 1 ], [ 0, 1, 0, 0 ], - [ 0, 1, 1, 0 ], [ 0, 1, 0, 1 ] ], - [ [ 1, 0, 0, 0 ], [ 1, 1, 1, 1 ], [ 1, 0, 1, 0 ], - [ 1, 0, 0, 1 ] ], - [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 1, 1, 1, 0 ], - [ 0, 0, 0, 0 ] ], - [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 0, 0 ], - [ 1, 1, 0, 1 ] ] ] ], - [ "relation", "B", 3, [ [ [ 1, 1, 1, 1 ], [ 0, 1, 0, 0 ], - [ 0, 1, 1, 0 ], [ 0, 1, 0, 1 ] ], - [ [ 1, 0, 0, 0 ], [ 1, 1, 1, 1 ], [ 1, 0, 1, 0 ], - [ 1, 0, 0, 1 ] ], - [ [ 1, 0, 0, 1 ], [ 0, 1, 0, 1 ], [ 1, 1, 1, 1 ], - [ 0, 0, 0, 1 ] ], - [ [ 1, 0, 1, 0 ], [ 0, 1, 1, 0 ], [ 0, 0, 1, 0 ], - [ 1, 1, 1, 1 ] ] ] ] ] ] ] -gap> -``` - ------------------------------------------------------------------------- - -Next Section: [Isofilter](m4-isofilter.html) - - ------------------------------------------------------------------------- - -*Prover9 Manual* - - -*Version 2009-11A* - ------------------------------------------------------------------------- - -# Prooftrans - -When Prover9 proves a theorem, it sends the proof to its output file in -a standard form. The standard form contains, for each step, -[justifications](output.html#just) with enough detail to reconstruct or -check the proof without any search. - -Prover9 proofs may contain non-clausal assumptions and -[goals](goals.html), as well as ordinary clauses. Non-clausal -assumptions are translated to clauses, and goals are negated and then -translated to clauses. See the proof in following example - -``` my_job -prover9 -f subset_trans.in > subset_trans.out -``` - -Prooftrans can extract proofs from Prover9 output files and transform -them in various ways, including the following. - -- No transformation, -- renumber steps, -- simplify justifications, -- expand all steps, turning secondary justifications into explicit - steps, -- produce proofs in XML, -- produce proofs for checking by the IVY proof checker, and -- produce hints for guiding subsequent searches. - -Prooftrans is part of the LADR/Prover9/Mace4 package. When the package -is installed, the Prooftrans program should be in the same directory as -Prover9 and Mace4. - -## Using Prooftrans - -The Prover9 output file containing the proof(s) is usually given to -Prooftrans with the argument "`-f `". If there is no -"`-f `" argument, Prooftrans takes its input from the standard -input. - -The arguments that tell Prooftrans what to do with the proof(s) are -described in the following sections, using the output file -[subset_trans.out](subset_trans.out) as a running example. - -If there is more than one proof in the file, the transformations will be -applied to each proof. The `hints` transformation collects all of the -clauses in the proof(s) into one list of hints. The other -transformations produce one proof for each proof in the input file. - -Here is a synopsis of the Prooftrans command; the arguments in square -brackets are optional. - -``` my_job -prooftrans [parents_only] [expand] [renumber] [striplabels] [-f file] -prooftrans xml [expand] [renumber] [striplabels] [-f file] -prooftrans ivy [renumner] [-f file] -prooftrans hints [-label label] [expand] [striplabels] [-f file] -``` - -Note that more than one transformation can be applied in several cases. -The option "striplabels" tells prooftrans to remove all label attributes -on clauses. - -Unfortunately, the output of Prooftrans usually cannot be used as the -input to another Prooftrans job, because Prooftrans expects its input to -have specific keywords and standard-form proofs. - ------------------------------------------------------------------------- - -### No Transformation - -If no additional argument is given, Prooftrans simply extracts the proof -from the Prover9 output file. - -``` my_job -prooftrans -f subset_trans.out > subset_trans.proof1 -``` - ------------------------------------------------------------------------- - -### Renumber the Steps - -The argument `renumber` tells Prooftrans to renumber the steps of each -proof consecutively, starting with step 1. The `expand`, `parents_only`, -and `xml` transformations can be used with the `renumber` -transformation. - -``` my_job -prooftrans renumber -f subset_trans.out > subset_trans.proof2 -``` - ------------------------------------------------------------------------- - -### Simplify Justifications - -The argument `parents_only` tells Prooftrans list only the parents in -the justifications, not the details about inference rules or positions. -The `expand` and `renumber` transformations can be used with the -`parents_only` transformation. - -``` my_job -prooftrans parents_only -f subset_trans.out > subset_trans.proof3 -``` - ------------------------------------------------------------------------- - -### Expand Steps - -The argument `expand` tells Prooftrans to produce more detailed proofs -in which - -- all hyper- and UR-resolution steps are replaced with binary resolution - steps, -- all demodulation sequences are replaced with paramodulation steps, and -- all unit deletion simplifications are replaced with resolution steps. - -*Note to author: this is a bad example, because only one step gets -expanded.* - -``` my_job -prooftrans expand -f subset_trans.out > subset_trans.proof4 -``` - -Note that when a step is expanded (step 22 in this example), the new -steps are identified by appending 'A', 'B', etc. to the number of the -original step. - -The `renumber`, `parents_only`, and `hints` transformations can be used -with the `expand` transformation. - ------------------------------------------------------------------------- - -### XML Proofs - -The options `xml` or `XML` tell Prooftrans to produce proofs in XML. The -options `expand` and `renumber` can be used with the XML transformation. - -``` my_job -prooftrans xml -f subset_trans.out > subset_trans.proof5.xml -``` - -The preceding output is displayed by your browser not as XML, but as -some transformation of the XML, because the XML refers to an XML -stylesheet, telling the browser how to transform the XML into HTML. - -To see the XML source, click "View -\> Frame Source" (or something like -that) in your browser while viewing the proof. - -Here is the [DTD for Prover9 XML proofs](proof3.dtd). (If you get an -error, click "View -\> Page Source".) - ------------------------------------------------------------------------- - -### IVY Proofs - -The options `ivy` or `IVY` tell Prooftrans to produce very detailed -proofs that can be checked with the [Ivy proof -checker](http://www.cs.unm.edu/~mccune/ivy_check_prover9/). - -``` my_job -prooftrans ivy -f subset_trans.out > subset_trans.proof6 -``` - -Ivy proofs have a only 5 types of step: `input`, `propositional`, -`new_symbol`, `flip`, `instantiate`, `resolve`, and `paramod`. The -`resolve` and `paramod` do not involve unification; instances are -generated first as separate steps, and then `resolve` or `paramod` are -applied to identical atomic formulas or terms. - -The Ivy proof checker cannot check steps justified by `new_symbol`. - ------------------------------------------------------------------------- - -### Proofs to Hints - -The option `hints` tells Prooftrans to take all of the proofs in the -file and produce one list of hints that can be given to Prover9 to guide -subsequent searches on related conjectures. - -``` my_job -prooftrans hints -f subset_trans.out > subset_trans.proof7 -``` - -If there is more than one proof in the file, the proofs will probably -share many steps. The list of hints that Prooftrans produces will be the -union of the steps in the proofs; that is, the duplicate steps will be -removed. - -The `expand` transformation can be used with the `hints` transformation. - -The label option tells prooftrans to attach label attributes to the hint -clauses. The labels consist of the string given on the command line and -a sequence number generated by prooftrans. The user's command shell may -require that the label be quoted, and if the the label is not a legal -LADR constant, prooftrans will enclose the label in double quotes. - -``` my_job -prooftrans hints -label 'job8' -f subset_trans.out > subset_trans.proof8 -``` - ------------------------------------------------------------------------- - -Next Section: [FOF-Prover9](fof-prover9.html) diff --git a/apn/lean/docs/python-flint/LICENSE b/apn/lean/docs/python-flint/LICENSE deleted file mode 100644 index 43c2ad50..00000000 --- a/apn/lean/docs/python-flint/LICENSE +++ /dev/null @@ -1,22 +0,0 @@ -MIT License - -Copyright (c) 2014-2016 Fredrik Johansson - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - diff --git a/apn/lean/docs/python-flint/python-flint.md b/apn/lean/docs/python-flint/python-flint.md deleted file mode 100644 index b03c5e42..00000000 --- a/apn/lean/docs/python-flint/python-flint.md +++ /dev/null @@ -1,375 +0,0 @@ - -# General concepts - -## Importing - -The `flint` module exposes a set of distinctly-named types together with -a small number of top-level functions and objects. Most functionality is -provided as methods on the types. This means that there should be no -namespace conflicts with most user code, with Python's builtin `math` -and `cmath` modules, or with packages such as `gmpy`, `numpy`, `sympy` -and `mpmath`. For typical interactive use, it should therefore generally -be safe to `import *`: - -> \>\>\> from flint import \* \>\>\> fmpq(3) / 2 3/2 - -For non-interactive use, it is still good manners to use explicit -imports or preserve the `flint` namespace prefix: - - >>> import flint - >>> flint.fmpq(3) / 2 - 3/2 - -## Global context - -Various settings are controlled by a global context object, `flint.ctx`. -Printing this object in the REPL shows the current settings, with a -brief explanation of each parameter: - - >>> from flint import ctx - >>> ctx - pretty = True # pretty-print repr() output - unicode = False # use unicode characters in output - prec = 53 # real/complex precision (in bits) - dps = 15 # real/complex precision (in digits) - cap = 10 # power series precision - threads = 1 # max number of threads used internally - -The user can mutate the properties directly, for example: - - >>> ctx.pretty = False - >>> fmpq(3,2) - fmpq(3,2) - >>> ctx.pretty = True - >>> fmpq(3,2) - 3/2 - -Calling `ctx.default()` restores the default settings. - -The special method `ctx.cleanup()` frees up internal caches used by -MPFR, FLINT and Arb. The user does normally not have to worry about -this. - -The context object `flint.ctx` can be controlled locally to increase the -working precision using python context managers: - - >>> arb(2).sqrt() - [1.41421356237309 +/- 5.15e-15] - >>> with ctx.extraprec(15): - ... arb(2).sqrt() - ... - [1.414213562373095049 +/- 2.10e-19] - -In the same manner, it is possible to exactly set the working precision, -or to update it in terms of digits: - - >>> with ctx.extradps(15): - ... arb(2).sqrt() - ... - [1.41421356237309504880168872421 +/- 6.27e-31] - >>> with ctx.workprec(15): - ... arb(2).sqrt() - ... - [1.414 +/- 2.46e-4] - -## Types and methods - -As a general rule, C functions associated with a type in FLINT or Arb -are exposed as methods of the corresponding Python type. - -For example, there is both an `.fmpq.bernoulli` (which computes a -Bernoulli number as an exact fraction) and `.arb.bernoulli` (which -computes a Bernoulli number as an approximate real number). - -A function that transforms a single value to the same type is usually an -ordinary method of that type, for instance `.arb.exp`. A function with a -different signature can either provided as a static method that takes -all inputs as function arguments, or as a method of the "primary" input, -taking the other inputs as arguments to the method (for example -`.arb.bessel_j`). - -When a method involves different types for inputs and outputs (or just -among the inputs), it will typically be a method of the more "complex" -type. For example, a matrix type is more "complex" than the underlying -scalar type, so `.fmpz_mat.det` is a method of the matrix type, -returning a scalar, and not vice versa. - -The method-based interface is intended to keep the code simple, not to -be aesthetically pleasing to mathematicians. A functional top-level -interface might be added in the future, allowing more idiomatic -mathematical notation (for example, `exp` and `det` as regular -functions). - -## Mutability - -Objects have immutable semantics. For example, the second line in: - - b = a - a += c - -leaves *b* unchanged. - -However, mutation via direct element access is supported for matrices -and polynomials. Some methods also allow explicitly performing the -operation in-place. Civilized users will restrict their use of such -methods to the point in the code where the object is first constructed: - - def create_thing(): # ok - a = thing() - a.mutate() - return a - -## Crashing and burning - -Very little overflow checking is done ahead-of-time. Trying to compute -an object far too large to hold in memory (for example, the exact -factorial of 2^{64}-1) will likely abort -the process, instead of raising an `OverflowError` or `MemoryError` that -can be caught at the Python level. - -Input that is obviously *invalid* (for example a negative number passed -as a length) can also cause crashes or worse things to happen. Ideally, -bad input should be caught at the Python level and result in appropriate -exceptions being raised, but this is not yet done systematically. At -this time, users should assume that invalid input leads to undefined -behavior! - -## Inexact numbers and numerical evaluation - -Real and complex numbers are represented by midpoint-radius intervals -(balls). All operations on real and complex numbers output intervals -representing rigorous error bounds. This also extends to polynomials and -matrices of real and complex numbers. - -The working precision for real and complex arithmetic is controlled by -the global context object attributes `ctx.prec` (in bits) `ctx.dps` (in -decimal digits). Changing either attribute changes the other to match. - -Be careful about using Python float and complex literals as input. Doing -`arb(0.1)` actually gives an interval containing the rational number - -> 3602879701896397 times 2^{-55} = -> 0.1000000000000000055511151231257827021181583404541015625 - -which might not be what you want. Do `arb("0.1")`, `arb("1/10")` or -`arb(fmpq(1,10))` if you want the correct decimal fraction. Small -integers and power-of-two denominators are still safe, for example -`arb(100.25)`. - -Pointwise boolean predicates (such as the usual comparison operators) -involving inexact numbers return *True* only if the predicate certainly -is true (i.e. it holds for all combinations of points that can be chosen -from the set-valued inputs), and return *False* if the predicate either -definitely is false or the truth cannot be determined. To determine that -a predicate is definitely false, test both the predicate and the inverse -predicate, e.g. if either `x < y` or `y <= x` returns *True*, then the -other is definitely false; if both return *False*, then neither can be -determined from the available data. - -The following convenience functions are provided for numerical -evaluation with adaptive working precision. - -## Power series - -Power series objects track the precision (the number of known terms) -automatically. The upper precision for power series is controlled by -`flint.ctx.cap`, with the default value 10. - -> \>\>\> fmpq_series(\[0,1\]).exp() 1 + x + 1/2\*x^2 + 1/6\*x^3 + -> 1/24\*x^4 + 1/120\*x^5 + 1/720\*x^6 + 1/5040\*x^7 + 1/40320\*x^8 + -> 1/362880\*x^9 + O(x^10) \>\>\> ctx.cap = 4 \>\>\> -> fmpq_series(\[0,1\]).exp() 1 + x + 1/2\*x^2 + 1/6\*x^3 + O(x^4) \>\>\> -> ctx.cap = 10 \>\>\> fmpq_series(\[0,1\], prec=5).exp() 1 + x + -> 1/2\*x^2 + 1/6\*x^3 + 1/24\*x^4 + O(x^5) -> -> \>\>\> ctx.cap = 3 \>\>\> ctx.dps = 10 \>\>\> -> arb_series(\[1,3,4\]).exp() (\[2.718281828 +/- 4.79e-10\]) + -> (\[8.154845485 +/- 4.36e-10\])*x + (\[23.10539554 +/- 2.25e-9\])*x^2 + -> O(x^3) \>\>\> ctx.default() - - - -# **fmpz** – integers¶ - -class flint.fmpz(*\*args*)¶ -The *fmpz* type represents an arbitrary-size integer. - - >>> fmpz(3) ** 25 - 847288609443 - - -Methods available on `fmpz` (see upstream docs for details): - - bell_number bin_uiui bit_length divisor_sigma euler_number euler_phi - fac_ui factor factor_smooth fib_ui gcd height_bits - is_perfect_power is_prime is_probable_prime is_square is_zero isqrt - jacobi lcm moebius_mu partitions_p primorial_ui repr - rising root sqrt sqrtmod sqrtrem stirling_s1 - stirling_s2 str - - -# **fmpq** – rational numbers¶ - -class flint.fmpq(*\*args*)¶ -The fmpq type represents multiprecision rational numbers. - - >>> fmpq(1,7) + fmpq(50,51) - 401/357 - - -Methods available on `fmpq` (see upstream docs for details): - - bernoulli ceil dedekind_sum denom floor gcd - harmonic height_bits is_zero next numer repr - round sqrt str trunc - - -# **fmpz_poly** – polynomials over integers¶ - -class flint.fmpz_poly(*\*args*)¶ -The *fmpz_poly* type represents dense univariate polynomials over the -integers. - - >>> fmpz_poly([1,2,3]) ** 3 - 27*x^6 + 54*x^5 + 63*x^4 + 44*x^3 + 21*x^2 + 6*x + 1 - >>> divmod(fmpz_poly([2,0,1,1,6]), fmpz_poly([3,5,7])) - (0, 6*x^4 + x^3 + x^2 + 2) - - -Methods available on `fmpz_poly` (see upstream docs for details): - - chebyshev_t chebyshev_u coeffs complex_roots content cos_minpoly - cyclotomic deflate derivative discriminant factor factor_squarefree - gcd height_bits hilbert_class_poly inflate is_constant is_cyclotomic - is_gen is_one is_zero leading_coefficient left_shift mul_low - pow_trunc real_roots repr resultant right_shift roots - sqrt str swinnerton_dyer truncate - - -# **nmod** – integers mod wordsize n¶ - -class flint.nmod(*val*, *mod*)¶ -The nmod type represents elements of Z/nZ for word-size n. - - >>> nmod(10,17) * 2 - 3 - - -Methods available on `nmod` (see upstream docs for details): - - is_zero modulus repr sqrt str - - -# **arb** – real numbers¶ - -class flint.arb(*mid=None*, *rad=None*)¶ -Represents a real number \\x\\ by a midpoint \\m\\ and a radius \\r\\ -such that \\x \in \[m \pm r\] = \[m-r, m+r\]\\. The midpoint and radius -are both floating-point numbers. The radius uses a fixed, -implementation-defined precision (30 bits). The precision used for -midpoints is controlled by `ctx.prec` (bits) or equivalently `ctx.dps` -(digits). - -The constructor accepts a midpoint *mid* and a radius *rad*, either of -which defaults to zero if omitted. The arguments can be tuples \\(a, -b)\\ representing exact floating-point data \\a 2^b\\, integers, -floating-point numbers, rational strings, or decimal strings. If the -radius is nonzero, it might be rounded up to a slightly larger value -than the exact value passed by the user. - - >>> arb(10.25) - 10.2500000000000 - >>> print(1 / arb(4)) # exact - 0.250000000000000 - >>> print(1 / arb(3)) # approximate - [0.333333333333333 +/- 3.71e-16] - >>> print(arb("3.0")) - 3.00000000000000 - >>> print(arb("0.1")) - [0.100000000000000 +/- 2.23e-17] - >>> print(arb("1/10")) - [0.100000000000000 +/- 2.23e-17] - >>> print(arb("3.14159 +/- 0.00001")) - [3.1416 +/- 2.01e-5] - >>> ctx.dps = 50 - >>> print(arb("1/3")) - [0.33333333333333333333333333333333333333333333333333 +/- 3.78e-51] - >>> ctx.default() - -Converting to or from decimal results in some loss of accuracy. See -`arb.str()` for details. - - -Methods available on `arb` (see upstream docs for details): - - abs_lower abs_upper acos acosh agm airy - airy_ai airy_ai_zero airy_bi airy_bi_zero asin asinh - atan atan2 atanh backlund_s bell_number bernoulli - bernoulli_poly bessel_i bessel_j bessel_k bessel_y beta_lower - bin bin_uiui bits ceil chebyshev_t chebyshev_u - chi ci const_catalan const_e const_euler const_glaisher - const_khinchin const_log10 const_log2 const_sqrt_pi contains contains_integer - contains_interior cos cos_pi cos_pi_fmpq cosh cot - cot_pi coth coulomb coulomb_f coulomb_g csc - csch digamma ei erf erfc erfcinv - erfi erfinv exp expint expm1 fac - fac_ui fib floor fmpq fmpz fresnel_c - fresnel_s gamma gamma_fmpq gamma_lower gamma_upper gegenbauer_c - gram_point hermite_h hypgeom hypgeom_0f1 hypgeom_1f1 hypgeom_2f1 - hypgeom_u intersection jacobi_p laguerre_l lambertw legendre_p - legendre_p_root legendre_q lgamma li log log1p - log_base lower man_exp max mid mid_rad_10exp - min nan neg neg_inf nonnegative_part overlaps - partitions_p pi polylog pos_inf rad rel_accuracy_bits - rel_one_accuracy_bits repr rgamma rising rising2 rising_fmpq_ui - root rsqrt sec sech sgn shi - si sin sin_cos sin_cos_pi sin_cos_pi_fmpq sin_pi - sin_pi_fmpq sinc sinc_pi sinh sinh_cosh sqrt - str tan tan_pi tanh union unique_fmpz - upper zeta zeta_nzeros - - -# **acb** – complex numbers¶ - -class flint.acb(*real=None*, *imag=None*)¶ -An *acb* represents a complex number by a rectangular enclosure -consisting of *arb* balls for the real and imaginary parts. - - >>> from flint import fmpq - >>> acb(2) - 2.00000000000000 - >>> acb(2+3j) - 2.00000000000000 + 3.00000000000000j - >>> acb("2 +/- 0.001", fmpq(2,3)) - [2.00 +/- 1.01e-3] + [0.666666666666667 +/- 4.82e-16]j - >>> acb(-1) ** 0.25 - [0.707106781186547 +/- 6.14e-16] + [0.707106781186547 +/- 6.15e-16]j - - -Methods available on `acb` (see upstream docs for details): - - abs_lower abs_upper acos acosh agm airy - airy_ai airy_bi arg asin asinh atan - atanh barnes_g bernoulli_poly bessel_i bessel_j bessel_k - bessel_y beta_lower bits chebyshev_t chebyshev_u chi - ci complex_rad conjugate contains contains_integer contains_interior - cos cos_pi cosh cot cot_pi coth - coulomb coulomb_f coulomb_g csc csch csgn - dft digamma dirichlet_eta dirichlet_l ei elliptic_e - elliptic_e_inc elliptic_f elliptic_inv_p elliptic_invariants elliptic_k elliptic_p - elliptic_pi elliptic_pi_inc elliptic_rc elliptic_rd elliptic_rf elliptic_rg - elliptic_rj elliptic_roots elliptic_sigma elliptic_zeta erf erfc - erfi exp exp_pi_i expint expm1 fresnel_c - fresnel_s gamma gamma_lower gamma_upper gegenbauer_c hermite_h - hypgeom hypgeom_0f1 hypgeom_1f1 hypgeom_2f1 hypgeom_u integral - jacobi_p laguerre_l lambertw legendre_p legendre_q lerch_phi - lgamma li log log1p log_barnes_g log_sin_pi - mid modular_delta modular_eta modular_j modular_lambda modular_theta - neg overlaps pi polygamma polylog pow - rad real_abs real_ceil real_floor real_heaviside real_max - real_min real_sgn real_sqrt rel_accuracy_bits rel_one_accuracy_bits repr - rgamma rising rising2 root rsqrt sec - sech sgn shi si sin sin_cos - sin_cos_pi sin_pi sinc sinc_pi sinh sinh_cosh - spherical_y sqrt stieltjes str tan tan_pi - tanh union unique_fmpz zeta zeta_zero zeta_zeros \ No newline at end of file diff --git a/apn/lean/docs/regina/LICENSE b/apn/lean/docs/regina/LICENSE deleted file mode 100644 index 1e06c482..00000000 --- a/apn/lean/docs/regina/LICENSE +++ /dev/null @@ -1,470 +0,0 @@ - - Regina - Software for low-dimensional topology - Copyright (c) 1999-2023, The Regina development team - - -CITATION: - -If you find Regina useful in your research, please consider citing it as -you would any other paper that you use. A suggested form of reference is: - - Benjamin A. Burton, Ryan Budney, William Pettersson, et al., - "Regina: Software for low-dimensional topology", - http://regina-normal.github.io/, 1999-2023. - - -AUTHORS: - -The primary developers of Regina are: - - Benjamin Burton - Ryan Budney - William Pettersson - -Many others have been of assistance with this project, be it through time, -knowledge, testing or code. Please see the full list of acknowledgements -in the users' handbook. - - -COPYING AND MODIFICATION: - -This program is free software; you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the -Free Software Foundation; either version 2 of the License, or (at your -option) any later version. - -Some of this code comes with additional permissions; see the section -below regarding online distribution. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -A full copy of the GNU General Public License should be included below; -if not, write to the Free Software Foundation, Inc., 51 Franklin St, -Fifth Floor, Boston, MA 02110-1301, USA. - - -ONLINE DISTRIBUTION: - -Regina's own source code comes with the following permissions in -addition to the GNU General Public License: - -As an exception, when this program is distributed through (i) the -App Store by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or -(iii) Google Play by Google Inc., then that store may impose any -digital rights management, device limits and/or redistribution -restrictions that are required by its terms of service. - -Some third-party libraries included in Regina are not granted this -exception, and must be removed from any build that is distributed on -stores that cannot comply with the GNU General Public License (such as -Apple's App Store). See the third-party licenses below for details. - - -SNAPPEA AND SNAPPY: - -Regina includes portions of the SnapPea kernel and its successor SnapPy, -which it uses for some geometric calculations. The SnapPea kernel was -originally written by Jeff Weeks. SnapPy, where this kernel is now maintained, -is primarily developed by Marc Culler, Nathan Dunfield and Matthias Goerner, -with contributions from many people. SnapPy and the corresponding SnapPea -kernel are distributed under the terms of the GNU General Public License, -version 2 or any later version, as published by the Free Software Foundation. - - -NORMALIZ LIBRARY: - -Regina includes a copy of libnormaliz, which it uses to help with the -enumeration of fundamental normal surfaces. Normaliz was written by Winfried -Bruns, Christof Soeger and others. It is distributed under the terms of -the GNU General Public License as published by the Free Software Foundation, -either version 3 of the License, or (at your option) any later version. - - -PYBIND11: - -Regina includes a copy of pybind11, which it uses to generate python bindings -for Regina's native C++ code. The pybind11 library was written by -Wenzel Jakob, and is distributed under a BSD-style license that is shipped -with Regina's source code in the file python/pybind11/LICENSE. - - -PYTHON RLCOMPLETER MODULE: - -Regina includes a modified copy of the Python rlcompleter module, which it -uses for tab completion in the graphical user interface. The original -rlcompleter module was distributed under the Python Software Foundation -License Version 2; the full license and copyright notice are shipped with -Regina's source code in the file python/regina/LICENSE. - - -ORB KERNEL: - -Regina includes snippets of code from Orb, for use in importing and -exporting files in Orb / Casson format. Orb is based on SnapPea -(see above) with additional code written by Damian Heard, who has also -given permission for his code to be distributed under the terms of the -GNU General Public License. - - -SYNTAX HIGHLIGHTING: - -Regina's graphical user interfaces incorporate a modified version of the KDE -syntax-highlighting framework, which they use for highlighting Python scripts. -This framework is distributed under the GNU Library General Public License, -version 2 or any later version, as published by the Free Software Foundation. - - -ICONS: - -Many of Regina's icons are custom-made, and are under the same license as -Regina. Some system icons are taken from the Humanity icon set (licensed -under the GNU General Public License version 2) and the Oxygen icon set -(licensed under the GNU Lesser General Public License version 3 or later). -Regina's die icon is based on an image from openclipart.org, which has been -released into the public domain. - - - - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. diff --git a/apn/lean/docs/regina/regina-python.md b/apn/lean/docs/regina/regina-python.md deleted file mode 100644 index bdf556a9..00000000 --- a/apn/lean/docs/regina/regina-python.md +++ /dev/null @@ -1,948 +0,0 @@ - - - -## Chapter 9. Python Scripting - -**Table of Contents** - - - - - - - - - - - - - - - - - - - - - - - - - - - -Regina contains inbuilt scripting, which offers you fine control over -Regina's mathematical engine and enables you to automate large amounts -of processing. You can write and run scripts from directly within -Regina, or you can use the separate command-line tool -. - -The user interface will stay in sync with any changes that you make -through a script, which means you can happily modify a data file via -scripts while you have it open. - -All scripts in Regina use the Python programming language -(). The specific Python -version must be chosen at build time. If you download a ready-made -package then the packager has already chosen the Python version for you; -the ready-made packages on the Regina website will always use the -default version of Python on each system where possible. - -### Warning - -Regina's Python interface typically assumes you know what you are doing, -and so the onus is on you to follow the rules. All constraints, -preconditions and so on are thoroughly documented in the . Probably the -easiest way to crash Regina is to bring up a Python console and do -something “illegal” (like gluing together two tetrahedra that belong to -different triangulations). - -## Starting a Python Session - -There are several ways of starting a Python session to work with Regina: - -### Graphical Python Consoles - -You can open a graphical Python console by selecting Tools→Python -Console from the menu (or by pressing the corresponding toolbar button). - -! - -A new console window will open as illustrated below, with an input area -down the bottom (see the red arrow) and a full history of the session in -the main part of the window. You can save this history by selecting -Console→Save Session. - -! - -When you start the Python session, Regina will set some special -variables for you: - -`item` -If you have a packet selected in the tree when you start the Python -session, the variable `item` will refer to this packet (see the figure -above for an example of this). - -Note that, if you later change your selection in the packet tree, the -`item` variable will not change as a result. - -`root` -The variable `root` will refer to the hidden root at the top of your -packet tree (this root is not visible in the user interface, but its -top-level children are). - -You are welcome to use these variables to change packets in your data -file (or even add, remove or rename packets): the graphical user -interface will always stay in sync with any changes that you make via -Python. - -### Command-Line Sessions - -You can run the command-line program - without a -graphical user interface at all. This will use the standard Python -interpreter. Since this is a text-based interface, you can also redirect -input and output in the usual way (using \< and \> in your command -shell). - -! - -macOS users will find **regina-python** inside Regina's application -bundle. See the  -for details. - -Windows users do not have the command-line **regina-python** at all, -though they can still use  and -. - -### Script Packets - -You can create a new  in your data -file. Script packets allow you to save Python scripts along with your -data, and they give your scripts easy access to the packets inside your -file. - -! - -When you open a script packet, you will see your Python code in the -lower part of the script editor, and a table of variables up the top. - -! - -You can add your own variables to this table, and set them to arbitrary -packets within your data file. Regina will always set these variables to -the corresponding packets before running your script. - -! - -At the top of the script editor you will find buttons to compile and run -your script. Compiling is optional: it merely gives you a chance to spot -syntax errors as you go. When you press Run, Regina will run your script -in a new graphical Python console. The console will be left open in case -you wish to experiment further. - -! - -Again, you are welcome to change packets in your data file via scripts -(or even add, remove or rename packets): the graphical user interface -will always stay in sync with any changes that your scripts make. - -## Accessing Regina from Python - -All of Regina's objects, classes and methods belong to the module called -*`regina`*. For instance, the main 3-manifold triangulation class is -`regina.Triangulation3`, the main knot/link class is `regina.Link`, and -the main routine to read a data file is `regina.open`. - -### Automatic Imports - -Whenever Regina gives you access to Python (either through a , a , or a -), it will -automatically import the *`regina`* module (i.e., “`import regina`”), -and it will import all of Regina's objects, classes and methods into the -current namespace (i.e., “`from regina import *`”). As a single -exception, it will *not* import `regina.open`, so as to not hide -Python's own `open()` function. - -This means, for instance, that you can create a new triangulation by -just calling `Triangulation3()`, but to read a data file you should -still call `regina.open(filename)`. For command-line sessions, if you -wish to avoid the heavy-handed “`from regina import *`”, you can pass -the option `--noautoimport` to **regina-python** (in which case you will -need to use fully qualified names such as `regina.Triangulation3()`). - -## API Documentation - -Regina includes a complete API reference for its calculation engine, -which describes in detail the objects, classes and methods that are -available through Python. To read this documentation, you can: - -- read the locally installed documentation by selecting Help→Python API - Reference; -- read it online through the ; -- read it inline from  - (see below). - -Be aware that this API documentation is primarily written for C++ (the -main language that Regina is written in). This means: - -- The documentation uses C++ notation and C++ types, though these are - all translated in the natural way to Python (e.g., `std::string` - becomes a Python string, and `std::vector` becomes a Python list). -- Some functions differ in how they are called from C++ versus Python. - In such cases you will see the C++ description, but there will also be - a “Python” paragraph explaining how things differ in Python. - -There are more issues that Python users should be aware of; please do -read the  -that outlines the main differences. - -### Inline Documentation - -Since version; 7.2, Regina now provides Python docstrings for all of its -classes and functions. This means that you can get help directly from -the Python prompt, as illustrated below. - -Be aware, however, that this documentation is extracted automatically -from the hand-written C++ API documentation discussed above. Although -great attention has been paid to making this extraction as useful and -natural as possible, it is still automated. Therefore you will find: - -- The documentation still uses some C++ terminology (e.g., - `std::string`, pointers and references, move semantics, etc.). -- Function arguments are often not named in the synopsis at the - beginning of the docstring (you will see them called `arg0`, `arg1`, - etc.). However, they *are* named in the detailed descriptions of the - arguments that follow. -- Some functions differ in how they are called from C++ versus Python - (e.g., `Tetrahedron3.face()`, or `Link.rewrite()`). In these cases, - the detailed hand-written argument descriptions will follow the C++ - variant, but the initial synopsis will be written for Python. For - clarity, here the arguments in the Python synopsis *will* be named. - Look also for a “Python” paragraph that explains exactly how the C++ - and Python versions differ. -- Some parts of the documentation are not accessible at all through - Python, since they do not correspond to entities that hold docstrings - (e.g., class constants such as `Perm4::nPerms`, or standalone pages - such as the discussion on Seifert fibred space notation). - -Ultimately, *it is the C++ documentation that is authoritative*, not the -inline Python documentation. Again, remember that you can always . - -An example of docstrings for member functions: - -``` programlisting ->>> help(NormalSurface.components) -Help on instancemethod in module regina.engine: - -components(...) - components(self: regina.NormalSurface) -> List[regina.NormalSurface] - - Splits this surface into connected components. - - A list of connected components will be returned. These components will - always be encoded using standard (tri-quad or tri-quad-oct) - coordinates, regardless of the internal vector encoding that is used - by this surface. - - Precondition: - This normal surface is embedded (not singular or immersed). - - Precondition: - This normal surface is compact (has finitely many discs). - - .. warning:: - This routine explicitly builds the normal discs, and so may run - out of memory if the normal coordinates are extremely large. - - Returns: - the list of connected components. -``` - -An example of docstrings for classes: - -``` programlisting ->>> help(Crossing) -Help on class Crossing in module regina.engine: - -class Crossing(pybind11_builtins.pybind11_object) - | Represents a single crossing in a link diagram. The two strands of the - | link that run over and under the crossing respectively can be accessed - | through routines such as over(), under(), upper(), lower(), and - | strand(). - | - | Each crossing has a sign, which is either positive (denoted by +1) or - | negative (denoted by -1): - | - | * In a positive crossing, the upper strand passes over the lower - | strand from left to right: - | - | ``` - | -----\ /-----> - | \ - | -----/ \-----> - | ``` - | - | * In a negative crossing, the upper strand passes over the lower - | strand from right to left: - | - | ``` - | -----\ /-----> - | / - | -----/ \-----> - | ``` - | - | If a link has *n* crossings, then these are numbered 0,...,*n*-1. The - | number assigned to this crossing can be accessed by calling index(). - | Note that crossings in a link may be reindexed when other crossings - | are added or removed - if you wish to track a particular crossing - | through such operations then you should use a pointer to the relevant - | Crossing object instead. - | - | ... (documentation continues) ... -``` - -## Talking with SnapPy - -Since Regina 4.95, a default installation of Regina can talk directly -with a default installation of SnapPy on many platforms. This includes -macOS 10.7 or greater (if you installed the SnapPy app bundle in the -usual `Applications` folder), and GNU/Linux (if your SnapPy uses the -default system Python installation). - -Simply type **`import snappy`** from within any of Regina's Python -environments. To send information back and forth between Regina and -SnapPy: - -- Regina's triangulation classes `Triangulation3` and - `SnapPeaTriangulation` both have a `snapPea()` function, which gives a - string that you can pass to SnapPy's `Manifold` constructor. - -- SnapPy's `Manifold` class has a `_to_string()` function, which gives a - string that you can pass to Regina's `Triangulation3` or - `SnapPeaTriangulation` constructor. - -Regarding fillings and peripheral curves: Regina does not store fillings -or peripheral curves for its own native , -as represented by the `Triangulation3` class. However, it does store -fillings and peripheral curves for its hybrid , as -represented by the `SnapPeaTriangulation` class. The trade-off is that -the native `Triangulation3` class offers Regina's full fine-grained -control over the triangulation, whereas the hybrid -`SnapPeaTriangulation` class has a more limited (largely read-only) -interface. - -- When sending data from Regina to SnapPy, if your triangulation is of - the class `Triangulation3`, then `Triangulation3.snapPea()` will - create a SnapPy manifold in which all fillings and peripheral curves - are marked as unknown. If your triangulation is of the class - `SnapPeaTriangulation`, and if you already have fillings and - peripheral curves stored on each cusp, then - `SnapPeaTriangulation.snapPea()` will create a SnapPy manifold that - preserves these. - -- Conversely, when sending data from SnapPy to Regina, you can choose to - instantiate a triangulation using either the `Triangulation3` class or - the `SnapPeaTriangulation` class. If you use the `Triangulation3` - class then all fillings and peripheral curves will be lost. If you use - the `SnapPeaTriangulation` class then fillings and peripheral curves - will be preserved (but your interface will be more restricted). - -If you wish to send the complement of a native Regina `Link` to SnapPy, -you can pass your link directly to the `SnapPeaTriangulation` -constructor, which will preserve the peripheral curves from the link -diagram; then you can pass this to SnapPy via -`SnapPeaTriangulation.snapPea()` as above. - -Regarding the interface: the `SnapPeaTriangulation` class inherits from -`Triangulation3`, and so you can use it anywhere that a read-only -triangulation is expected (in particular, you can use it for enumerating -vertex normal surfaces or angle structures). However, because -`SnapPeaTriangulation` must maintain two synchronised copies of the -triangulation (Regina's and SnapPea's), it is essentially read-only: any -attempt to modify the triangulation using Regina's native routines -(e.g., `pachner()` or `barycentricSubdivision()`) will cause the SnapPea -triangulation to delete itself and become a “null triangulation” -instead. - -### Warning - -At present, SnapPy (version 2.0.3) is not compatible with multiple -Python interpreters. If you import SnapPy into more than one Python -console in the graphical user interface, SnapPy may stop working. See - -for details. - -The following Python session illustrates several of the concepts -discussed above. - -``` programlisting -bab@ember:~$ regina-python -Regina 7.2 -Software for low-dimensional topology -Copyright (c) 1999-2022, The Regina development team ->>> import snappy ->>> m = snappy.Manifold('m001') ->>> t = SnapPeaTriangulation(m._to_string()) ->>> print t.detail() -Size of the skeleton: - Tetrahedra: 2 - Triangles: 4 - Edges: 2 - Vertices: 1 - -Tetrahedron gluing: - Tet | glued to: (012) (013) (023) (123) - -----+------------------------------------------------------- - 0 | 1 (103) 1 (320) 1 (210) 1 (132) - 1 | 0 (320) 0 (102) 0 (310) 0 (132) - -Vertices: - Tet | vertex: 0 1 2 3 - -----+-------------------------- - 0 | 0 0 0 0 - 1 | 0 0 0 0 - -Edges: - Tet | edge: 01 02 03 12 13 23 - -----+-------------------------------- - 0 | 0 1 1 1 1 0 - 1 | 0 1 1 1 1 0 - -Triangles: - Tet | face: 012 013 023 123 - -----+------------------------ - 0 | 0 1 2 3 - 1 | 2 0 1 3 - -Tetrahedron shapes: - 0: ( -1.60812e-16, 1 ) - 1: ( -1.60812e-16, 1 ) - -Cusps: - 0: Vertex 0, complete - ->>> print t.hasStrictAngleStructure() -True ->>> print AngleStructures(t).detail() -4 vertex angle structures (no restrictions): -0 1 0 ; 1 0 0 -0 0 1 ; 1 0 0 -1 0 0 ; 0 1 0 -1 0 0 ; 0 0 1 - ->>> t2 = Example3.figureEight() ->>> m2 = snappy.Manifold(t2.snapPea()) ->>> print m2.volume() -2.02988321282 ->>> - -``` - -## Sample Python Sessions - -Several sample Python sessions are reproduced below. Each session was -started by running **`regina-python`** from the command line. - -### Working with a triangulation - -``` programlisting -example$ regina-python -Regina 7.0 -Software for low-dimensional topology -Copyright (c) 1999-2021, The Regina development team ->>> ################################ ->>> # ->>> # Sample Python Script ->>> # ->>> # Illustrates different queries and actions on a 3-manifold triangulation ->>> # and its normal surfaces. ->>> # ->>> # See the file "triangulation.session" for the results of running this ->>> # script. ->>> # ->>> ################################ ->>> ->>> # Create a new (3,4,7) layered solid torus. This is a 3-tetrahedron ->>> # triangulation of a solid torus. ->>> t = Example3.lst(3, 4) ->>> print(t) -Bounded orientable 3-D triangulation, f = ( 1 5 7 3 ) ->>> ->>> # Print the full skeleton of the triangulation. ->>> print(t.detail()) -Size of the skeleton: - Tetrahedra: 3 - Triangles: 7 - Edges: 5 - Vertices: 1 - -Tetrahedron gluing: - Tet | glued to: (012) (013) (023) (123) - -----+------------------------------------------------------- - 0 | boundary boundary 1 (012) 1 (130) - 1 | 0 (023) 0 (312) 2 (013) 2 (120) - 2 | 1 (312) 1 (023) 2 (312) 2 (230) - -Vertices: - Tet | vertex: 0 1 2 3 - -----+-------------------------- - 0 | 0 0 0 0 - 1 | 0 0 0 0 - 2 | 0 0 0 0 - -Edges: - Tet | edge: 01 02 03 12 13 23 - -----+-------------------------------- - 0 | 0 1 2 2 1 3 - 1 | 1 2 3 3 2 4 - 2 | 2 4 3 3 4 3 - -Triangles: - Tet | face: 012 013 023 123 - -----+------------------------ - 0 | 0 1 2 3 - 1 | 2 3 4 5 - 2 | 5 4 6 6 - ->>> ->>> # Calculate some algebraic properties of the triangulation. ->>> print(t.homology()) -Z ->>> print(t.homologyBdry()) -2 Z ->>> ->>> # Test for 0-efficiency, which asks Regina to search for certain types ->>> # of normal surfaces. ->>> print(t.isZeroEfficient()) -False ->>> ->>> # Make our own list of vertex normal surfaces in standard coordinates. ->>> surfaces = NormalSurfaces(t, NormalCoords.Standard) ->>> ->>> # Print the full list of vertex normal surfaces. ->>> print(surfaces.detail()) -Embedded, vertex surfaces -Coordinates: Standard normal (tri-quad) -Number of surfaces is 9 -1 1 1 1 ; 0 0 0 || 1 1 0 0 ; 1 0 0 || 0 0 0 0 ; 0 2 0 -0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0 -0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0 -0 0 0 0 ; 0 0 2 || 0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 -1 1 0 0 ; 0 0 1 || 1 1 0 0 ; 0 0 0 || 0 0 0 0 ; 0 1 0 -3 3 0 0 ; 0 0 1 || 1 1 0 0 ; 0 0 2 || 1 1 0 0 ; 0 0 1 -0 0 1 1 ; 1 0 0 || 1 1 0 0 ; 1 0 0 || 0 0 0 0 ; 0 2 0 -0 0 0 0 ; 0 1 0 || 0 0 0 0 ; 1 0 0 || 0 0 0 0 ; 0 1 0 -1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0 - ->>> ->>> # Print the Euler characteristic and orientability of each surface. ->>> for s in surfaces: -... print("Chi =", s.eulerChar(), "; Or =", s.isOrientable()) -... -Chi = -1 ; Or = True -Chi = 0 ; Or = True -Chi = 0 ; Or = True -Chi = 0 ; Or = True -Chi = 0 ; Or = False -Chi = 1 ; Or = True -Chi = -2 ; Or = True -Chi = -1 ; Or = False -Chi = 1 ; Or = True ->>> ->>> # List all surfaces with more than one quad in the first tetrahedron. ->>> for s in surfaces: -... if s.quads(0,0) + s.quads(0,1) + s.quads(0,2) > 1: -... print(s) -... -0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0 -0 0 0 0 ; 0 0 2 || 0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 ->>> -``` - -### Working with a packet tree - -``` programlisting -example$ regina-python -Regina 7.0 -Software for low-dimensional topology -Copyright (c) 1999-2021, The Regina development team ->>> ################################ ->>> # ->>> # Sample Python Script ->>> # ->>> # Illustrates the traversal and manipulation of an entire packet tree. ->>> # ->>> # See the file "tree.session" for the results of running this script. ->>> # ->>> ################################ ->>> ->>> # Recreate the original SnapPea census of cusped hyperbolic manifolds ->>> # triangulated by at most 5 tetrahedra. ->>> # ->>> # Since we are building a packet tree, we need to use PacketOfTriangulation3, ->>> # not the plain type Triangulation3 (which is not a packet type). ->>> census = Container() ->>> for i in range(415): -... mfd = SnapPeaCensusManifold(SnapPeaCensusManifold.SEC_5, i) -... census.append(make_packet(mfd.construct(), mfd.name())) -... ->>> # The triangulations are now all children of the "census" container. ->>> # Remove all triangulations with more than two tetrahedra. ->>> # ->>> # Since we are deleting children, we step through the children manually ->>> # instead of just iterating over children(). ->>> tri = census.firstChild() ->>> while tri != None: -... next = tri.nextSibling() -... if tri.size() > 2: -... tri.makeOrphan() -... tri = next -... ->>> # Print the homology of each remaining triangulation. ->>> # This time we are not adding or removing children, so we can just iterate. ->>> for tri in census.children(): -... print(tri.label() + ":", tri.homology()) -... -Gieseking manifold: Z -SnapPea m001: Z + Z_2 -SnapPea m002: Z + Z_2 -SnapPea m003: Z + Z_5 -Figure eight knot complement: Z ->>> -``` - -### Reporting progress of long operations - -``` programlisting -example$ regina-python -Regina 7.0 -Software for low-dimensional topology -Copyright (c) 1999-2021, The Regina development team ->>> ################################ ->>> # ->>> # Sample Python Script ->>> # ->>> # Illustrates progress reporting during long operations. ->>> # ->>> # See the file "progress.session" for the results of running this script. ->>> # ->>> ################################ ->>> ->>> import threading ->>> import time ->>> ->>> # Create an 18-tetrahedron triangulation of a knot complement with real ->>> # boundary faces (not an ideal vertex). The knot is L106003 from the ->>> # knot/link census. We used Regina to truncate the ideal vertex, and ->>> # then copied the isomorphism signature so that we can reconstruct the ->>> # triangulation here. ->>> sig = 'sfLfvQvwwMQQQccjghjkmqlonrnrqpqrnsnksaisnrobocksks' ->>> tri = Triangulation3(sig) ->>> print(tri) -Bounded orientable 3-D triangulation, f = ( 1 20 37 18 ) ->>> ->>> # Create a progress tracker to use during the normal surface enumeration. ->>> # This will report the state of progress while the enumeration runs in ->>> # the background. ->>> tracker = ProgressTracker() ->>> ->>> # Start the normal surface enumeration in a new thread. ->>> surfaces = None ->>> def run(): -... global surfaces, tracker -... surfaces = NormalSurfaces(tri, NormalCoords.Standard, NormalList.Vertex, -... NormalAlg.Default, tracker) -... ->>> thread = threading.Thread(target = run) ->>> thread.start() ->>> ->>> # At this point the enumeration is up and running. ->>> # Output a progress report every quarter-second until it finishes. ->>> while not tracker.isFinished(): -... print('Progress:', tracker.percent(), '%') -... time.sleep(0.25) -... -Progress: 0.17578125 % -Progress: 54.20654296875 % -Progress: 91.80555555555556 % ->>> ->>> # The surface enumeration is now complete. ->>> thread.join() ->>> print(surfaces) -2319 embedded, vertex surfaces (Standard normal (tri-quad)) ->>> -``` - -## Name - -regina-python — Regina's command-line Python interface - -## Synopsis - -**regina-python** \[\[`-q, --quiet`\] \| \[`-v, --verbose`\]\] -\[`-n, --nolibs`\] \[`-a, --noautoimport`\] - -**regina-python** \[\[`-q, --quiet`\] \| \[`-v, --verbose`\]\] -\[`-n, --nolibs`\] \[`-a, --noautoimport`\] \[`-i, --interactive`\] -{*`script`*} \[*`script-args`*\] - -## Description - -Regina is a software package for 3-manifold and 4-manifold topologists, -with a focus on triangulations, knots and links, normal surfaces, and -angle structures. For 3-manifolds, it includes high-level tasks such as -3-sphere and unknot recognition, connected sum decomposition and -Hakenness testing, comes with a rich database of census manifolds, and -incorporates the SnapPea kernel for working with hyperbolic manifolds. -For 4-manifolds, it offers a range of combinatorial and algebraic tools, -plus support for normal hypersurfaces. For knots and links, Regina can -perform combinatorial manipulation, compute knot polynomials, and work -with several import/export formats. Regina comes with a full graphical -user interface, as well as Python bindings and a low-level C++ -programming interface. - -This command starts an interactive Python session for Regina. This will -be a command-line Python session, with direct text input/output and no -graphical user interface. All of the objects, clases and methods from -Regina's mathematical engine will be made available through the module -*`regina`*, which will be imported on startup (effectively running -`import regina`). Moreover, unless the option `--noautoimport` is -passed, all of Regina's objects, classes and methods will be imported -directly into the current namespace (effectively running -`from regina import *`). - -Instead of starting an interactive Python session, you can pass a Python -script (with arguments if desired). In this case Regina will run the -script (after first importing the *`regina`* module). If you pass -`--interactive`, Regina will leave you at a Python prompt once the -script finishes; otherwise it will exit Python and return you to the -command line. - -## Options - -`-q`, `--quiet` -Start in quiet mode. No output will be produced except for serious -errors. In particular, warnings will be suppressed. - -This is equivalent to setting the environment variable -*`REGINA_VERBOSITY`*=`0`. - -`-v`, `--verbose` -Start in verbose mode. Additional diagnostic information will be output. - -This is equivalent to setting the environment variable -*`REGINA_VERBOSITY`*=`2`. - -`-a`, `--noautoimport` -Still import the *`regina`* module, but do not automatically import all -of Regina's objects, classes and methods into the current namespace -(that is, do not run `from regina import *`). This means that (for -example) the main 3-manifold triangulation class must be accessed as -`regina.Triangulation3`, not just `Triangulation3`. - -`-i`, `--interactive` -Run the script in interactive mode. After executing the given script, -Regina will leave you in the Python interpreter to run your own -additional commands. - -This option is only available when a script is passed. If no script is -passed, **regina-python** will always start in interactive mode. - -## Environment Variables - -The following environment variables influence the behaviour of this -program. Most variables can also be set in the local configuration file -`~/.regina-python` using a line of the form *`option`*=*`value`*; -exceptions are noted below. Environment variables take precedence over -values in the configuration file. - -*`REGINA_VERBOSITY`* -Specifies how much output should be generated. Recognised values are: - -`0` -Display errors only; this is equivalent to passing the option `--quiet`. - -`1` -Display errors and warnings; this is the default. - -`2` -Display errors, warnings and diagnostic output; this is equivalent to -passing the option `--verbose`. - -*`REGINA_PYTHON`* -The command used to start the Python interpreter. - -In general you should use the same version of Python that Regina was -built against; otherwise Python might not be able to load the *`regina`* -module. - -Normally you should not need to set this option yourself. By default, -Regina will use the same Python installation that it was built against. - -*`REGINA_PYLIBDIR`* -The directory containing the Python module *`regina`*. - -If you have installed Regina's Python module in a standard Python -location (i.e., Python can import it directly without extending -`sys.path`), then *`REGINA_PYLIBDIR`* should be left empty or undefined. - -Normally you should not need to set this option yourself. This program -should know how to find Regina's Python module in standard situations, -which include fixed filesystem installations (e.g., GNU/Linux and -Windows), relocatable app bundles (e.g., macOS), and running directly -from the source tree. - -*`REGINA_HOME`* -The directory beneath which Regina's data files are installed. In -particular, Regina's census lookup routines will look for the census -databases in the subdirectory *`$REGINA_HOME`*`/data/census/`. - -This option can only be set from the environment: it cannot be set in -the configuration file `~/.regina-python`. - -Normally you should not need to set this option yourself. This program -should know how to find its data files in standard situations, which -include fixed filesystem installations (e.g., GNU/Linux and Windows), -relocatable app bundles (e.g., macOS), and running directly from the -source tree. - -## macOS Users - -If you downloaded a drag-and-drop app bundle, this utility is shipped -inside it. If you dragged Regina to the main Applications folder, you -can run it as `/Applications/Regina.app/Contents/MacOS/regina-python`. - -## Windows Users - -The command **regina-python** is not available under Windows. However, -you can still use Python scripting in Regina's graphical user interface, -by opening a graphical Python console or using script packets. - -## See Also - -. - -Regina comes with thorough API documentation, which describes in detail -all of the objects, classes and methods that Regina makes available to -Python. You can access this documentation via Help→Python API Reference -in the graphical user interface, or read it online at -. - -## Author - -Many people have been involved in the development of Regina; see the - for a full list -of credits. - --  --  - - \|  - -regina::Census Class Reference - - - -A utility class used to search for triangulations across one or more -3-manifold census databases.  - -`#include ` - -## Detailed Description - -A utility class used to search for triangulations across one or more -3-manifold census databases. - -This class consists of static routines only. The main entry point (and -typically the only way that you would use this class) is via the various -static - -routines. - -Warning -This class is not thread-safe, in that it performs some global -initialisation the first time one of the - -functions is called. If you need thread-safety, you can always call - -with an empty string when initialising your program, and ensure this has -finished before you allow any subsequent "normal" calls to - -from other threads. - -## Member Function Documentation - -## lookup() \[1/2\] - -Searches for the given triangulation through all of Regina's in-built -census databases. - -For this routine you specify the triangulation by giving its isomorphism -signature, as returned by -. -This is faster than the variant , -since Regina's census databases store isomorphism signatures internally. -If you do not already know the isomorphism signature, it is fine to just -call  -instead. - -Note that there may be many hits (possibly from multiple databases, and -in some cases possibly even within the same database). Therefore a -*list* of hits will be returned, which you can iterate through the -individual matches. Even if there are no matches at all, a list will -still be returned; you can call empty() on this list to test whether any -matches were found. - -This routine is fast: it first computes the isomorphism signature of the -triangulation, and then performs a logarithmic-time lookup in each -database (here "logarithmic" means logarithmic in the size of the -database). - -Parameters - -  - -Returns -a list of all database matches. - -## lookup() \[2/2\] - -Searches for the given triangulation through all of Regina's in-built -census databases. - -Internally, the census databases store isomorphism signatures as opposed -to fully fleshed-out triangulations. If you already have the isomorphism -signature of the triangulation, then you can call the variant - -instead, which will be faster since it avoids some extra overhead. - -Note that there may be many hits (possibly from multiple databases, and -in some cases possibly even within the same database). Therefore a -*list* of hits will be returned, which you can iterate through the -individual matches. Even if there are no matches at all, a list will -still be returned; you can call empty() on this list to test whether any -matches were found. - -This routine is fast: it first computes the isomorphism signature of the -triangulation, and then performs a logarithmic-time lookup in each -database (here "logarithmic" means logarithmic in the size of the -database). - -Parameters - -  - -Returns -a list of all database matches. - ------------------------------------------------------------------------- - -The documentation for this class was generated from the following file: - -- census/ - ------------------------------------------------------------------------- - -Copyright © 1999–2025, The Regina development team - diff --git a/apn/lean/docs/snappy/LICENSE b/apn/lean/docs/snappy/LICENSE deleted file mode 100644 index a825130a..00000000 --- a/apn/lean/docs/snappy/LICENSE +++ /dev/null @@ -1,351 +0,0 @@ -License -======= - -Copyright 2007-present by Marc Culler, Nathan Dunfield, Matthias -Goerner, Jeff Weeks and others. - -This code is released under the `GNU General Public License, version 2 -`_ or (at your option) any -later version as published by the Free Software Foundation. - ----------------------------------------------------------------------- - - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. diff --git a/apn/lean/docs/snappy/snappy.md b/apn/lean/docs/snappy/snappy.md deleted file mode 100644 index 6c4709ec..00000000 --- a/apn/lean/docs/snappy/snappy.md +++ /dev/null @@ -1,1238 +0,0 @@ - - -# Tutorial - -The easiest way to learn to use SnapPy is to watch the screencasts -available on YouTube: - -- Intro and quickstart: an 11 minute video with the basics: Part - I and Part - II. - -- An hour-long demo Practical computation with hyperbolic - 3-manifolds, recorded at the Thurston - Memorial Conference. - -- The SnapPy 2.0 new feature demo. - -- SnapPy, SageMath, and Docker are - friends with - associated materials (4 pages), including - homework. - -- Notes, problem sheets, and - references from the LMS-CMI - Research School in Warwick in 2017. - -- Another hour-long demo Practical computations with hyperbolic - 3-manifolds given - at ICERM in 2019. - -The **key** thing to remember when using the SnapPy command shell window -is that you can explore objects using introspection and tab-completion: - - In [1]: Manifold? - ...instructions for creating a manifold... - -So now we create a manifold: - - In [2]: M = Manifold("m004") - -But what can we do with it? - - In [3]: M. - ...list of methods... - -What does the “cover” method do? - - In [4]: M.cover? - ...description of cover method.. - -# The snappy module and its classes - -SnapPy is centered around a Python interface for SnapPea called -“snappy”, and this is what you’re interacting with in the main “SnapPy -command shell” window. The main class is Manifold, which is an ideal -triangulation of the interior of a compact 3-manifold with torus -boundary, where each tetrahedron has been assigned the geometry of an -ideal tetrahedron in hyperbolic 3-space. A Dehn-filling can be specified -for each boundary component, allowing the description of closed -3-manifolds and some orbifolds. The class Manifold is derived from the -simpler Triangulation class which lacks any geometric structure. There -are also some additional classes for things like fundamental groups, -Dirichlet domains, etc. Snappy comes with a large library of -3-manifolds, some of which are grouped together in censuses. - -- Manifold: the main class - - `Manifold` -- ManifoldHP: High-precision variant - - FAQ -- Triangulation - - `Triangulation` -- Additional Classes - - AbelianGroup - - FundamentalGroup - - SymmetryGroup - - DirichletDomain - - CuspNeighborhood -- Census manifolds - - `OrientableCuspedCensus` - - `OrientableClosedCensus` - - `CensusKnots` - - `LinkExteriors` - - `HTLinkExteriors` - - `RibbonLinks` - - `NonorientableCuspedCensus` - - `NonorientableClosedCensus` - - Censuses of Platonic manifolds - - `ManifoldTable` - - `AlternatingKnotExteriors` - - `NonalternatingKnotExteriors` - -# Manifold: the main class - -*class *snappy.Manifold -A Manifold is a -`Triangulation` -together with a geometric structure. That is, a Manifold is an ideal -triangulation of the interior of a compact 3-manifold with torus and -Klein-bottle boundary components, where each tetrahedron has been -assigned the geometry of an ideal tetrahedron in hyperbolic 3-space. A -Dehn-filling can be specified for each boundary component, allowing the -description of closed 3-manifolds, some orbifolds and cone 3-manifolds. -Here’s a quick example: - - >>> M = Manifold('9_42') - >>> M.volume() - 4.05686022 - >>> M.cusp_info('shape') - [-4.278936315 + 1.95728679*I] - -This is an example for running SnapPy inside Sage: - - sage: import snappy - sage: M = snappy.Manifold('m125(1,2)(4,5)') - sage: M.is_orientable() - True - -An alternative way of running SnapPy inside Sage: - - sage: from snappy import * - sage: M = Manifold('m123') - sage: M.num_cusps() - 1 - -A Manifold can be specified in a number of ways, e.g. - -- Manifold(‘9_42’) : The complement of the knot 9_42 in S^3. - -- Manifold(‘m125(1,2)(4,5)’) : The SnapPea census manifold m125 where - the first cusp has Dehn filling (1,2) and the second cusp has filling - (4,5). - -- Manifold() : Opens a link editor window where can you specify a link - complement. - -In general, the specification can be from among the below, with -information on Dehn fillings added. - -- SnapPea cusped census manifolds: e.g. ‘m123’, ‘s123’, ‘v123’. - -- Link complements: - - > - Rolfsen’s table: e.g. ‘4_1’, ‘04_1’, ‘5^2_6’, ‘6_4^7’, ‘L20935’, - > ‘l104001’. - > - > - Hoste-Thistlethwaite Knotscape table: e.g. ‘11a17’ or ‘12n345’ - > - > - Callahan-Dean-Weeks-Champanerkar-Kofman-Patterson knots: e.g. - > ‘K6_21’. - > - > - Dowker-Thistlethwaite code: e.g. ‘DT:\[(6,8,2,4)\]’ - -- Once-punctured torus bundles: e.g. ‘b++LLR’, ‘b+-llR’, ‘bo-RRL’, - ‘bn+LRLR’ - -- Fibered manifold associated to a braid: ‘Braid\[1,2,-3,4\]’ - - Here, the braid is thought of as a mapping class of the punctured - disc, and this manifold is the corresponding mapping torus. If you - want the braid closure, do (1,0) filling of the last cusp. - -- From mapping class group data using Twister: - - ‘Bundle(S\_{1,1}, \[a0, B1\])’ or ‘Splitting(S\_{1,0}, \[b1, A0\], - \[a0,B1\])’ - - See the help for the ‘twister’ module for more. - -- A SnapPea triangulation or link projection file: ‘filename’ - - The file will be loaded if found in the current directory or the path - given by the shell variable `SNAPPEA_MANIFOLD_DIRECTORY`. See - `Manifold.save()` for - details. - -- A string containing the contents of a SnapPea triangulation or link - projection file. - -chern_simons(*accuracy=False*) -Returns the Chern-Simons invariant of the manifold (normalized by -dividing it by \\2 \pi^2\\), if it is known. - - >>> M = Manifold('m015') - >>> M.chern_simons() - -0.15320413 - -The return value has an extra attribute, accuracy, which is the number -of digits of accuracy as *estimated* by SnapPea. - - >>> cs, accuracy = M.chern_simons(accuracy = True) - >>> accuracy in (8, 9, 56, 57) # Low and High precision - True - -By default, when the manifold has at least one cusp, Zickert’s algorithm -is used; when the manifold is closed we use SnapPea’s original -algorithm, which is based on Meyerhoff-Hodgson-Neumann. - -Note: When computing the Chern-Simons invariant of a closed manifold, -one must sometimes compute it first for the unfilled manifold so as to -initialize SnapPea’s internals. For instance, - - >>> M = Manifold('5_2') - >>> M.chern_simons() - -0.15320413 - >>> M.dehn_fill( (1,2) ) - >>> M.chern_simons() - 0.07731787 - -works, but will fail with -`ValueError:`` ``The`` ``Chern-Simons`` ``invariant`` ``isn't`` ``currently`` ``known.` -if the first call to chern_simons is not made. - -complex_volume(*verified_modulo_2_torsion=False*, *bits_prec=None*) -Returns the complex volume modulo \\i \pi^2\\ which is given by - -\\\text{vol} + i \text{CS}\\ - -where \\\text{CS}\\ is the (unnormalized) Chern-Simons invariant. - - >>> M = Manifold('5_2') - >>> M.complex_volume() - 2.82812209 - 3.02412838*I - -Note that -`chern_simons` -normalizes the Chern-Simons invariant by dividing it by \\2 \pi^2 = -19.7392...\\ - - >>> M.chern_simons() - -0.153204133297152 - -More examples: - - >>> M.dehn_fill((1,2)) - >>> M.complex_volume() - 2.22671790 + 1.52619361*I - >>> M = Manifold("3_1") # A non-hyperbolic example. - >>> cvol = M.complex_volume() - >>> cvol.real() - 0 - >>> cvol.imag() - -1.64493407 - -If no cusp is filled or there is only one cusped (filled or unfilled), -the complex volume can be verified up to multiples of \\i \pi^2 /2\\ by -passing `verified_modulo_2_torsion`` ``=`` ``True` when inside SageMath. -Higher precision can be requested with `bits_prec`: - - sage: M = Manifold("m015") - sage: M.complex_volume(verified_modulo_2_torsion=True, bits_prec = 93) # doctest: +NUMERIC21 - 2.828122088330783162764? + 1.910673824035377649698?*I - sage: M = Manifold("m015(3,4)") - sage: M.complex_volume(verified_modulo_2_torsion=True) # doctest: +NUMERIC6 - 2.625051576? - 0.537092383?*I - -cover(*permutation_rep*) → snappy.Manifold -Returns a `Manifold` representing -the finite cover specified by a transitive permutation representation. -The representation is specified by a list of permutations, one for each -generator of the simplified presentation of the fundamental group. Each -permutation is specified as a list `P` such such that -`set(P)`` ``==`` ``set(range(d))` where `d` is the degree of the cover. - - >>> M = Manifold('m004') - >>> N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]]) - >>> abs(N0.volume()/M.volume() - 5) < 0.0000000001 - True - -If within SageMath, the permutations can also be of type -`PermutationGroupElement`, in which case they act on the set -`range(1,`` ``d`` ``+`` ``1)`. Or, you can specify a GAP or Magma -subgroup of the fundamental group. Some examples: - - sage: M = Manifold('m004') - -The basic method: - - sage: N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]]) - -From a Gap subgroup: - - sage: G = gap(M.fundamental_group()) - sage: H = G.LowIndexSubgroupsFpGroup(5)[9] - sage: N1 = M.cover(H) - sage: N0 == N1 - True - -Or a homomorphism to a permutation group: - - sage: f = G.GQuotients(PSL(2,7))[1] - sage: N2 = M.cover(f) - sage: N2.volume()/M.volume() # doctest: +NUMERIC9 - 8.00000000 - -Or maybe we want larger cover coming from the kernel of this: - - sage: N3 = M.cover(f.Kernel()) - sage: N3.volume()/M.volume() # doctest: +NUMERIC9 - 168.00000000 - -Check the homology against what Gap computes directly: - - sage: N3.homology().betti_number() - 32 - sage: len([ x for x in f.Kernel().AbelianInvariants().sage() if x == 0]) - 32 - -We can do the same for Magma: - - sage: G = magma(M.fundamental_group()) #doctest: +SKIP - sage: Q, f = G.pQuotient(5, 1, nvals = 2) #doctest: +SKIP - sage: M.cover(f.Kernel()).volume() #doctest: +SKIP - 10.14941606 - sage: h = G.SimpleQuotients(1, 11, 2, 10000)[1,1] #doctest: +SKIP - sage: N4 = M.cover(h) #doctest: +SKIP - sage: N2 == N4 #doctest: +SKIP - True - -cover_info() -If this is a manifold or triangulation which was constructed as a -covering space, return a dictionary describing the cover. Otherwise -return 0. The dictionary keys are ‘base’, ‘type’ and ‘degree’. - -covers(*degree*, *method: Optional\[str\] = None*, *cover_type: str = 'all'*) → list\[snappy.Manifold\] -Returns a list of `Manifold`s -corresponding to all of the finite covers of the given degree. The -default method is ‘low_index’ for general covers and ‘snappea’ for -cyclic covers. The former uses Sim’s algorithm while the latter uses the -original Snappea algorithm. - -WARNING: If the degree is large this might take a very, very, very long -time. - - >>> M = Manifold('m003') - >>> covers = M.covers(4) - >>> sorted(N.homology() for N in covers) - [Z/3 + Z/15 + Z, Z/5 + Z + Z] - -It is faster to look just at cyclic covers. - - >>> covers = M.covers(4, cover_type='cyclic') - >>> [(N, N.homology()) for N in covers] - [(m003~cyc~0(0,0), Z/3 + Z/15 + Z)] - -Here we check that we get the same number of covers with the ‘snappea’ -and ‘low_index’ methods. - - >>> M = Manifold('m125') - >>> len(M.covers(5)) - 19 - >>> len(M.covers(5, method='snappea')) - 19 - -If you are using Sage, you can use GAP to find the subgroups, which is -often much faster, by specifying the optional argument method = ‘gap’ If -you have Magma installed, you can used it to do the heavy lifting by -specifying method=’magma’. - -cusp_info(*data_spec=None*, *verified=False*, *bits_prec=None*) -Returns an info object containing information about the given cusp. -Usage: - - >>> M = Manifold('v3227(0,0)(1,2)(3,2)') - >>> M.cusp_info(1) - Cusp 1 : torus cusp with Dehn filling coefficients (M, L) = (1.0, 2.0) - -To get more detailed information about the cusp, we do - - >>> c = M.cusp_info(0) - >>> c.shape - 0.11044502 + 0.94677098*I - >>> c.modulus - -0.12155872 + 1.04204128*I - >>> sorted(c.keys()) - ['filling', 'holonomies', 'holonomy_accuracy', 'index', 'is_complete', 'modulus', 'shape', 'shape_accuracy', 'topology'] - -Here ‘shape’ is the shape of the cusp, i.e. (longitude/meridian) and -‘modulus’ is its shape in the geometrically preferred basis, i.e. ( -(second shortest translation)/(shortest translation)). For cusps that -are filled, one instead cares about the holonomies: - - >>> M.cusp_info(-1)['holonomies'] - (-0.59883089 + 1.09812548*I, 0.89824633 + 1.49440443*I) - -The complex numbers returned for the shape and for the two holonomies -have an extra attribute, accuracy, which is SnapPea’s *estimate* of -their accuracy. - -You can also get information about multiple cusps at once: - - >>> M.cusp_info() - [Cusp 0 : complete torus cusp of shape 0.11044502 + 0.94677098*I, - Cusp 1 : torus cusp with Dehn filling coefficients (M, L) = (1.0, 2.0), - Cusp 2 : torus cusp with Dehn filling coefficients (M, L) = (3.0, 2.0)] - >>> M.cusp_info('is_complete') - [True, False, False] - -The cusp shapes can be verified: - - sage: M = Manifold('m292') - sage: M.cusp_info('shape', verified = True, bits_prec = 60) # doctest: +NUMERIC12 - [-0.1766049820997? + 1.2028208192855?*I, - -0.1766049820997? + 1.2028208192855?*I] - -dehn_fill(*filling_data*, *which_cusp=None*) → None -Set the Dehn filling coefficients of the cusps. This can be specified in -the following ways, where the cusps are numbered by 0,1,…,(num_cusps - -1). - -- Fill cusp 2: - - >>> M = Manifold('8^4_1') - >>> M.dehn_fill((2,3), 2) - >>> M - 8^4_1(0,0)(0,0)(2,3)(0,0) - -- Fill the last cusp: - - >>> M.dehn_fill((1,5), -1) - >>> M - 8^4_1(0,0)(0,0)(2,3)(1,5) - -- Fill the first two cusps: - - >>> M.dehn_fill( [ (3,0), (1, -4) ]) - >>> M - 8^4_1(3,0)(1,-4)(2,3)(1,5) - -- When there is only one cusp, there’s a shortcut - - >>> N = Manifold('m004') - >>> N.dehn_fill( (-3,4) ) - >>> N - m004(-3,4) - -Does not return a new Manifold. - -filled_triangulation(*cusps_to_fill='all'*) → snappy.Manifold -Return a new Manifold where the specified cusps have been permanently -filled in. - -Filling all the cusps results in a Triangulation rather than a Manifold, -since SnapPea can’t deal with hyperbolic structures when there are no -cusps. - -Examples: - - >>> M = Manifold('m125(1,2)(3,4)') - >>> N = M.filled_triangulation() - >>> N.num_cusps() - 0 - -Filling cusps 0 and 2 : - - >>> M = Manifold('v3227(1,2)(3,4)(5,6)') - >>> M.filled_triangulation([0,2]) - v3227_filled(3,4) - -fundamental_group(*simplify_presentation: bool = True*, *fillings_may_affect_generators: bool = True*, *minimize_number_of_generators: bool = True*, *try_hard_to_shorten_relators: bool = True*) → HolonomyGroup -Return a -`HolonomyGroup` -representing the fundamental group of the manifold, together with its -holonomy representation. If integer Dehn surgery parameters have been -set, then the corresponding peripheral elements are killed. - - >>> M = Manifold('m004') - >>> G = M.fundamental_group() - >>> G - Generators: - a,b - Relators: - aaabABBAb - >>> G.peripheral_curves() - [('ab', 'aBAbABab')] - >>> G.SL2C('baaBA') - [ 2.50000000 - 2.59807621*I -6.06217783 - 0.50000000*I] - [ 0.86602540 - 2.50000000*I -4.00000000 + 1.73205081*I] - -There are three optional arguments all of which default to True: - -- simplify_presentation - -- fillings_may_affect_generators - -- minimize_number_of_generators - - >>> M.fundamental_group(False, False, False) - Generators: - a,b,c - Relators: - CbAcB - BacA - -homology() → AbelianGroup -Returns an -`AbelianGroup` -representing the first integral homology group of the underlying (Dehn -filled) manifold. - - >>> M = Triangulation('m003') - >>> M.homology() - Z/5 + Z - -identify(*extends_to_link=False*) -Looks for the manifold in all of the SnapPy databases. For hyperbolic -manifolds this is done by searching for isometries: - - >>> M = Manifold('m125') - >>> M.identify() - [m125(0,0)(0,0), L13n5885(0,0)(0,0), ooct01_00000(0,0)(0,0)] - -By default, there is no restriction on the isometries. One can require -that the isometry take meridians to meridians. This might return fewer -results: - - >>> M.identify(extends_to_link=True) - [m125(0,0)(0,0), ooct01_00000(0,0)(0,0)] - -For closed manifolds, extends_to_link doesn’t make sense because of how -the kernel code works: - - >>> C = Manifold("m015(1,2)") - >>> C.identify() - [m006(-5,2)] - >>> C.identify(True) - [] - -is_isometric_to(*other: Manifold \| ManifoldHP*, *return_isometries: bool = False*) → bool \| List\[Isometry\] -Returns `True` if M and N are isometric, `False` if they not. A -`RuntimeError` is raised in cases where the SnapPea kernel fails to -determine either answer. (This is fairly common for closed manifolds.) - - >>> M = Manifold('m004') - >>> N = Manifold('4_1') - >>> K = Manifold('5_2') - >>> M.is_isometric_to(N) - True - >>> N.is_isometric_to(K) - False - -We can also get a complete list of isometries between the two manifolds: - - >>> M = Manifold('5^2_1') # The Whitehead link - >>> N = Manifold('m129') - >>> isoms = M.is_isometric_to(N, return_isometries = True) - >>> isoms[6] # Includes action on cusps - 0 -> 1 1 -> 0 - [1 2] [-1 -2] - [0 -1] [ 0 1] - Extends to link - -Each transformation between cusps is given by a matrix which acts on the -left. That is, the two *columns* of the matrix give the image of the -meridian and longitude respectively. In the above example, the meridian -of cusp 0 is sent to the meridian of cusp 1. - -Note: The answer `True` is rigorous, but the answer `False` may not be -as there could be numerical errors resulting in finding an incorrect -canonical triangulation. - -is_orientable() → bool -Return whether the underlying 3-manifold is orientable. - - >>> M = Triangulation('x124') - >>> M.is_orientable() - False - -is_two_bridge() → bool -If the manifold is the complement of a two-bridge knot or link in -\\S^3\\, then this method returns \\(p,q)\\ where \\p/q\\ is the -fraction describing the link. Otherwise, returns `False`. - - >>> M = Manifold('m004') - >>> M.is_two_bridge() - (2, 5) - >>> M = Manifold('m016') - >>> M.is_two_bridge() - False - -Note: An answer of `True` is rigorous, but not the answer `False`, as -there could be numerical errors resulting in finding an incorrect -canonical triangulation. - -normal_surfaces(*algorithm='FXrays'*) -All the vertex spun-normal surfaces in the current triangulation. - - >>> M = Manifold('m004') - >>> M.normal_surfaces() - [, - , - , - ] - -num_cusps(*cusp_type='all'*) → int -Return the total number of cusps. By giving the optional argument -‘orientable’ or ‘nonorientable’ it will only count cusps of that type. - - >>> M = Triangulation('m125') - >>> M.num_cusps() - 2 - -num_tetrahedra() → int -Return the number of tetrahedra in the triangulation. - - >>> M = Triangulation('m004') - >>> M.num_tetrahedra() - 2 - -simplify(*passes_at_fours=6*) -Try to simplify the triangulation by doing Pachner moves. - - >>> M = Triangulation('12n123') - >>> M.simplify() - -It does four kinds of moves that reduce the number of tetrahedra: - -- 3 -\> 2 and 2 -\> 0 Pacher moves, which eliminate one or two - tetrahedra respectively. - -- On suitable valence-1 edges, does a 2 -\> 3 and then 2 -\> 0 move, - which removes a tetrahedron and creates a new valence-1 edge. - -- When a 2-simplex has two edges of valence-4 giving rise to the - suspension of a pentagon, replace these 6 tetrahedra with a single - edge of valence 5. - -It also does random 4 -\> 4 moves in hopes of setting up a -simplfication. The argument passes_at_fours is the number of times it -goes through the valence-4 edges without progress before giving up. - -solution_type(*enum=False*) -Returns the type of the current solution to the gluing equations, -basically a summary of how degenerate the solution is. If the flag -`enum=True` is set, then an integer value is returned. The possible -answers are: - -- 0: `not`` ``attempted` - -- 1: `all`` ``tetrahedra`` ``positively`` ``oriented` aka - *geometric_solution* - - Should correspond to a genuine hyperbolic structure. - -- 2: `contains`` ``negatively`` ``oriented`` ``tetrahedra` aka - *nongeometric solution* - - Probably corresponds to a hyperbolic structure but some simplices have - reversed orientations. - -- 3: `contains`` ``flat`` ``tetrahedra` (should be called - `all`` ``tetrahedra`` ``flat`) - - All tetrahedra have shape in \\\mathbb{R} - \\0, 1\\\\. - -- 4: `contains`` ``degenerate`` ``tetrahedra` - - Some shapes are close to \\\\0,1, \infty\\\\. - -- 5: `unrecognized`` ``solution`` ``type` - -- 6: `no`` ``solution`` ``found` - - >>> M = Manifold('m007') - >>> M.solution_type() - 'all tetrahedra positively oriented' - >>> M.dehn_fill( (3,1) ) - >>> M.solution_type() - 'contains negatively oriented tetrahedra' - >>> M.dehn_fill( (3,-1) ) - >>> M.solution_type() - 'contains degenerate tetrahedra' - -symmetry_group(*of_link: bool = False*) → SymmetryGroup -Returns the symmetry group of the Manifold. If the flag “of_link” is -set, then it only returns symmetries that preserves the meridians. - -verify_hyperbolicity(*verbose=False*, *bits_prec=None*, *holonomy=False*, *fundamental_group_args=\[\]*, *lift_to_SL=True*) -Given an orientable SnapPy Manifold, verifies its hyperbolicity. - -Similar to HIKMOT’s -`verify_hyperbolicity()`, -the result is either `(True,`` ``listOfShapeIntervals)` or -`(False,`` ``[])` if verification failed. `listOfShapesIntervals` is a -list of complex intervals (elements in sage’s `ComplexIntervalField`) -certified to contain the true shapes for the hyperbolic manifold. - -Higher precision intervals can be obtained by setting `bits_prec`: - - sage: from snappy import Manifold - sage: M = Manifold("m019") - sage: M.verify_hyperbolicity() # doctest: +NUMERIC12 - (True, [0.780552527850? + 0.914473662967?*I, 0.780552527850? + 0.91447366296773?*I, 0.4600211755737? + 0.6326241936052?*I]) - - sage: M = Manifold("t02333(3,4)") - sage: M.verify_hyperbolicity() # doctest: +NUMERIC9 - (True, [2.152188153612? + 0.284940667895?*I, 1.92308491369? + 1.10360701507?*I, 0.014388591584? + 0.143084469681?*I, -2.5493670288? + 3.7453498408?*I, 0.142120333822? + 0.176540027036?*I, 0.504866865874? + 0.82829881681?*I, 0.50479249917? + 0.98036162786?*I, -0.589495705074? + 0.81267480427?*I]) - -One can instead get a holonomy representation associated to the verified -hyperbolic structure. This representation takes values in 2x2 matrices -with entries in the `ComplexIntervalField`: - - sage: M = Manifold("m004(1,2)") - sage: success, rho = M.verify_hyperbolicity(holonomy=True) - sage: success - True - sage: trace = rho('aaB').trace(); trace # doctest: +NUMERIC9 - -0.1118628555? + 3.8536121048?*I - sage: (trace - 2).contains_zero() - False - sage: (rho('aBAbaabAB').trace() - 2).contains_zero() - True - -Here, there is **provably** a fixed holonomy representation rho0 from -the fundamental group G of M to SL(2, C) so that for each element g of G -the matrix rho0(g) is contained in rho(g). In particular, the above -constitutes a proof that the word ‘aaB’ is non-trivial in G. In -contrast, the final computation is consistent with ‘aBAbaabAB’ being -trivial in G, but *does not prove this*. - -A non-hyperbolic manifold (`False` indicates that the manifold might not -be hyperbolic but does **not** certify non-hyperbolicity. Sometimes, -hyperbolicity can only be verified after increasing the precision): - - sage: M = Manifold("4_1(1,0)") - sage: M.verify_hyperbolicity() - (False, []) - -Under the hood, the function will call the `CertifiedShapesEngine` to -produce intervals certified to contain a solution to the rectangular -gluing equations. It then calls -`check_logarithmic_gluing_equations_and_positively_oriented_tets` to -verify that the logarithmic gluing equations are fulfilled and that all -tetrahedra are positively oriented. - -volume(*accuracy=False*, *verified=False*, *bits_prec=None*) -Returns the volume of the current solution to the hyperbolic gluing -equations; if the solution is sufficiently non-degenerate, this is the -sum of the volumes of the hyperbolic pieces in the geometric -decomposition of the manifold. - - >>> M = Manifold('m004') - >>> M.volume() - 2.02988321 - >>> M.solution_type() - 'all tetrahedra positively oriented' - -The return value has an extra attribute, accuracy, which is the number -of digits of accuracy as *estimated* by SnapPea. When printing the -volume, the result is rounded to 1 more than this number of digits. - - >>> vol, accuracy = M.volume(accuracy = True) - >>> accuracy in (10, 63) # Low precision, High precision - True - -Inside SageMath, verified computation of the volume of a hyperbolic -manifold is also possible (this will verify first that the manifold is -indeed hyperbolic): - - sage: M.volume(verified=True, bits_prec=100) #doctest: +NUMERIC24 - 2.029883212819307250042405109? - -# Census manifolds - -Snappy comes with a large library of manifolds, which can be accessed -individually through the Manifold and Triangulation constructors but can -also be iterated through using the objects described on this page. - -SnapPy’s iterators support several flexible methods for accessing -manifolds. They can be sliced (i.e. restricted to subranges) either by -index or by volume. Calling the iterator with keyword arguments such as -num_tets=1, betti=2 or num_cusps=3 returns an iterator which is filtered -by the specified conditions. In addition these iterators can determine -whether they contain a given manifold. They support python’s “A in B” -syntax, and also provide an identify method which will return a copy of -the census manifold which is isometric to the manifold passed as an -argument. - -snappy.OrientableCuspedCensus* = OrientableCuspedCensus without filters* -Iterator for all orientable cusped hyperbolic manifolds that can be -triangulated with at most 10 ideal tetrahedra. See -[\[Li\]](https://arXiv.org/abs/2512.02142) for background on these -manifolds. - - >>> for M in OrientableCuspedCensus[3:6]: print(M, M.volume()) - ... - m007(0,0) 2.56897060 - m009(0,0) 2.66674478 - m010(0,0) 2.66674478 - >>> for M in OrientableCuspedCensus[-9:-6]: print(M, M.volume()) - ... - o10_150721(0,0)(0,0)(0,0) 10.1494160640965 - o10_150722(0,0)(0,0)(0,0) 10.1494160640965 - o10_150723(0,0)(0,0) 10.1494160640965 - >>> for M in OrientableCuspedCensus[4.10:4.11]: print(M, M.volume()) - ... - m217(0,0) 4.10795310 - m218(0,0) 4.10942659 - >>> for M in OrientableCuspedCensus(num_cusps=2)[:3]: - ... print(M, M.volume(), M.num_cusps()) - ... - m125(0,0)(0,0) 3.66386238 2 - m129(0,0)(0,0) 3.66386238 2 - m202(0,0)(0,0) 4.05976643 2 - >>> M = Manifold('m129') - >>> M in LinkExteriors - True - >>> LinkExteriors.identify(M) - 5^2_1(0,0)(0,0) - -  - -snappy.OrientableClosedCensus* = OrientableClosedCensus without filters* -Iterator for 11,031 closed hyperbolic manifolds from the census by -Hodgson and Weeks. - - >>> len(OrientableClosedCensus) - 11031 - >>> len(OrientableClosedCensus(betti=2)) - 1 - >>> for M in OrientableClosedCensus(betti=2): - ... print(M, M.homology()) - ... - v1539(5,1) Z + Z - -  - -snappy.CensusKnots* = CensusKnots without filters* -Iterator for all of the knot exteriors in the SnapPea Census, as -tabulated by Callahan, Dean, Weeks, Champanerkar, Kofman, Patterson, -Dunfield, and Li. These are the knot exteriors which can be triangulated -by at most 10 ideal tetrahedra. See -[\[Li\]](https://arXiv.org/abs/2512.02142) for more. - - >>> for M in CensusKnots[3.4:3.5]: - ... print(M, M.volume(), LinkExteriors.identify(M)) - ... - K4_3(0,0) 3.47424776 False - K5_1(0,0) 3.41791484 False - K5_2(0,0) 3.42720525 8_1(0,0) - K5_3(0,0) 3.48666015 9_2(0,0) - - >>> len(CensusKnots) - 3116 - >>> CensusKnots[-1].num_tetrahedra() - 10 - -  - -snappy.LinkExteriors* = LinkExteriors without filters* -Iterator for all knots with at most 11 crossings and links with at most -10 crossings, using the Rolfsen notation. The triangulations were -computed by Joe Christy. - - >>> for K in LinkExteriors(num_cusps=3)[-3:]: - ... print(K, K.volume()) - ... - 10^3_72(0,0)(0,0)(0,0) 14.35768903 - 10^3_73(0,0)(0,0)(0,0) 15.86374431 - 10^3_74(0,0)(0,0)(0,0) 15.55091438 - >>> M = Manifold('8_4') - >>> OrientableCuspedCensus.identify(M) - s862(0,0) - -By default, the ‘identify’ returns the first isometric manifold it -finds; if the optional ‘extends_to_link’ flag is set, it insists that -meridians are taken to meridians. - - >>> M = Manifold('7^2_8') - >>> LinkExteriors.identify(M) - 5^2_1(0,0)(0,0) - >>> LinkExteriors.identify(M, extends_to_link=True) - 7^2_8(0,0)(0,0) - -  - -snappy.HTLinkExteriors* = HTLinkExteriors without filters* -Iterator for all knots up to 14 or 15 crossings (see below for which) -and links up to 14 crossings as tabulated by Jim Hoste and Morwen -Thistlethwaite. In addition to the filter arguments supported by all -ManifoldTables, this iterator provides alternating=\; -knots_vs_links=\<’knots’/’links’\>; and crossings=N. These allow -iterations only through alternating or non-alternating links with 1 or -more than 1 component and a specified crossing number. - - >>> HTLinkExteriors.identify(LinkExteriors['8_20']) - K8n1(0,0) - >>> Mylist = HTLinkExteriors(alternating=False,knots_vs_links='links')[8.5:8.7] - >>> len(Mylist) - 8 - >>> for L in Mylist: - ... print( L.name(), L.num_cusps(), L.volume() ) - ... - L11n138 2 8.66421454 - L12n1097 2 8.51918360 - L14n13364 2 8.69338342 - L14n13513 2 8.58439465 - L14n15042 2 8.66421454 - L14n24425 2 8.60676092 - L14n24777 2 8.53123093 - L14n26042 2 8.64333782 - >>> for L in Mylist: - ... print( L.name(), L.DT_code() ) - ... - L11n138 [(8, -10, -12), (6, -16, -18, -22, -20, -2, -4, -14)] - L12n1097 [(10, 12, -14, -18), (22, 2, -20, 24, -6, -8, 4, 16)] - L14n13364 [(8, -10, 12), (6, -18, 20, -22, -26, -24, 2, -4, -28, -16, -14)] - L14n13513 [(8, -10, 12), (6, -20, 18, -26, -24, -4, 2, -28, -16, -14, -22)] - L14n15042 [(8, -10, 14), (12, -16, 18, -22, 24, 2, 26, 28, 6, -4, 20)] - L14n24425 [(10, -12, 14, -16), (-18, 26, -24, 22, -20, -28, -6, 4, -2, 8)] - L14n24777 [(10, 12, -14, -18), (2, 28, -22, 24, -6, 26, -8, 4, 16, 20)] - L14n26042 [(10, 12, 14, -20), (8, 2, 28, -22, -24, -26, -6, -16, -18, 4)] - -SnapPy comes with one of two versions of HTLinkExteriors. The smaller -original one provides knots and links up to 14 crossings; the larger -adds to that the knots (but not links) with 15 crossings. You can -determine which you have by whether - - >>> len(HTLinkExteriors(crossings=15)) - -gives 0 or 253293. To upgrade to the larger database, install the Python -module ‘snappy_15_knots’ as discussed on the ‘installing SnapPy’ -webpage. - -  - -snappy.RibbonLinks* = RibbonLinks without filters* -The database of ribbon links from Section 2.5 of [\[Dunfield and -Gong\]](https://arXiv.org/abs/2512.21825). Each link includes a -certificate describing the ribbon disks: - - >>> len(RibbonLinks(cusps=2)) - 12143 - >>> M = RibbonLinks[1000] - >>> M.name(), M.num_cusps(), M.volume() - ('ribbon_2_16_3079d007', 2, 22.9002274714046) - -The bands used show each link is ribbon are included. For this link, we -used 3 bands: - - >>> N = RibbonLinks['ribbon_2_23_f9c7aff2'] - >>> N.ribbon_cert[1::2] - ['0d1c54_1_0', '5e5709_1_0', '144f625e5d29_5_2'] - -  - -snappy.NonorientableCuspedCensus* = NonorientableCuspedCensus without filters* -Iterator for all nonorientable cusped hyperbolic manifolds that can be -triangulated with at most 5 ideal tetrahedra. - - >>> for M in NonorientableCuspedCensus(betti=2)[:3]: - ... print(M, M.homology()) - ... - m124(0,0)(0,0)(0,0) Z/2 + Z + Z - m128(0,0)(0,0) Z + Z - m131(0,0) Z + Z - -  - -snappy.NonorientableClosedCensus* = NonorientableClosedCensus without filters* -Iterator for 17 nonorientable closed hyperbolic manifolds from the -census by Hodgson and Weeks. - - >>> for M in NonorientableClosedCensus[:3]: print(M, M.volume()) - ... - m018(1,0) 2.02988321 - m177(1,0) 2.56897060 - m153(1,0) 2.66674478 - -There are also: - -- Censuses of Platonic manifolds - -As instances of subclasses of ManifoldTable, the objects above support -the following methods. - -*class *snappy.database.ManifoldTable(*table=''*, *db_path=None*, *mfld_hash=\*, *\*\*filter_args*) -Iterator for cusped manifolds in an sqlite3 table of manifolds. - -Initialize with the table name. The table schema is required to include -a text field called ‘name’ and a text field called ‘triangulation’. The -text holds the result of M.triangulation_isosig(), -M.triangulation_isosig(decorated = True), or M.\_to_string(). - -Both mapping from the manifold name, and lookup by index are supported. -Slicing can be done either by numerical index or by volume. - -The \_\_contains\_\_ method is supported, so M in T returns True if M is -isometric to a manifold in the table T. The method T.identify(M) will -return the matching manifold from the table. - -find(*where=None*, *order_by='id'*, *limit=None*, *offset=None*) -Return a list of up to limit manifolds stored in this table, satisfying -the where clause, and ordered by the order_by clause. If limit is None, -all matching manifolds are returned. If the offset parameter is set, the -first offset matches are skipped. - -identify(*mfld*, *extends_to_link=False*) -Look for a manifold in this table which is isometric to the argument. - -Return the matching manifold, if there is one which SnapPea declares to -be isometric. - -Return False if no manifold in the table has the same hash. - -Return None in all other cases (for now). - -If the flag “extends_to_link” is True, requires that the isometry sends -meridians to meridians. If the input manifold is closed this will result -in no matches being returned. - -keys() -Return the list of column names for this manifold table. - -siblings(*mfld*) -Return all manifolds in the census which have the same hash value. - -Because of the large size of their datasets, the classes below can only -iterate through slices by index, and do not provide the identification -methods. - -*class *snappy.AlternatingKnotExteriors(*indices=(0, 491327, 1)*) -Iterator/Sequence for Alternating knot exteriors from the -Hoste-Thistlethwaite tables. Goes through 16 crossings. - -  - -*class *snappy.NonalternatingKnotExteriors(*indices=(0, 1210608, 1)*) -Iterator/Sequence for nonAlternating knot exteriors from the -Hoste-Thistlethwaite tables. Goes through 16 crossings. - -# Verified computations - -## Introduction - -Several SnapPy methods use numerical computations with floating point -approximations and can potentially result in incorrect results. This -even applies to methods whose output is purely combinatorial such as -`canonical_retriangulation()`. - -Many of these SnapPy methods can be supplied with a `verified` flag to -ensure that the result is provably correct. Note that verified -computations are only available when using SnapPy inside -SageMath. If the flag `verified=True` is -specified, an incorrect result is never returned. Instead the method -clearly indicates a failure, usually through an exception: - - sage: M=Manifold("m004") - sage: M.drill_word('abc', verified=True, bits_prec = 40) - ... - InsufficientPrecisionError: When re-tracing the geodesic, the intersection with the next tetrahedron face was too close to the previous to tell them apart. Increasing the precision will probably avoid this problem. - -Often, such a failure can be advoided by increasing the precision. In -particular, this applies if the exception is a (subclass of) -`InsufficientPrecisionError`: - - sage: M.drill_word('abc', verified=True, bits_prec = 60) - m004_drilled(0,0)(0,0) - -Note that, -`verify_hyperbolicity()` -is different though and does not throw an exception. Instead, it returns -a bool indicating success as part of its output. This is for -compatibility with -HIKMOT’s -`verify_hyperbolicty`: - - sage: M.verify_hyperbolicity(bits_prec=10) - (False, []) - sage: M.verify_hyperbolicity() - (True, - [0.50000000000000? + 0.86602540378444?*I, - 0.50000000000000? + 0.86602540378444?*I]) - -As illustrated above, the result consists of intervals (of type -SageMath’s `RealIntervalField` or `ComplexIntervalField`) if the output -of a computation is numerical and `verified=True` is specified. These -intervals contain the true value. - -## Overview - -Some examples of verified computations are: - -- Verify the hyperbolicity of an orientable 3-manifold giving complex - intervals for the shapes corresponding to a hyperbolic structure or - holonomy representation with - `verify_hyperbolicity()`: - - sage: M = Manifold("m015") - sage: M.verify_hyperbolicity() - (True, - [0.6623589786224? + 0.5622795120623?*I, - 0.6623589786224? + 0.5622795120623?*I, - 0.6623589786224? + 0.5622795120623?*I]) - sage: M.verify_hyperbolicity(holonomy=True)[1].SL2C('a') - [-0.324717957? - 1.124559024?*I -0.704807293? + 0.398888830?*I] - [ 1.409614585? - 0.797777659?*I -1.000000000? + 0.?e-9*I] - -- Intervals for the volume and complex volume of a hyperbolic orientable - 3-manifold: - - sage: M = Manifold("m003(-3,1)") - sage: M.volume(verified=True, bits_prec = 100) - 0.942707362776927720921299603? - sage: M = Manifold("m015") - sage: M.complex_volume(verified_modulo_2_torsion=True) - 2.8281220883? + 1.9106738240?*I - - (Note that when using verified computation, the Chern-Simons invariant - is only computed modulo pi^2/2 even though it is defined modulo pi^2.) - -- Give the (a close relative to the canonical cell decomposition) of a - cusped hyperbolic manifold using intervals or exact arithmetic if - necessary with - `canonical_retriangulation()`: - - sage: M = Manifold("m412") - sage: K = M.canonical_retriangulation(verified = True) - sage: len(K.isomorphisms_to(K)) # Certified size of isometry group - 8 - - **Remark:** For the case of non-tetrahedral canonical cell, exact - values are used which are found using the - LLL-algorithm - and then verified using exact computations. These computations can be - slow. A massive speed-up was achieved by recent improvements so that - the computation of the isometry signature of any manifold in - `OrientableCuspedCensus` takes at most a couple of seconds, typically, - far less. Manifolds with more simplices might require setting a higher - value for `exact_bits_prec_and_degrees`. - -- The isometry signature which is a complete invariant of the isometry - type of a cusped hyperbolic manifold (i.e., two manifolds are - isometric if and only if they have the same isometry signature): - - sage: M = Manifold("m412") - sage: M.isometry_signature(verified = True) - 'mvvLALQQQhfghjjlilkjklaaaaaffffffff' - - The isometry signature can be strengthened to include the peripheral - curves such that it is a complete invariant of a hyperbolic link: - - sage: M = Manifold("L5a1") - sage: M.isometry_signature(of_link = True, verified = True) - 'eLPkbdcddhgggb_baCbbaCb' - - See - `isometry_signature()` - for details. - - **Remark:** The isometry signature is based on the canonical - retriangulation so the same warning applies. - -- The maximal cusp area matrix which characterizes the configuration - space of disjoint cusp neighborhoods with - `cusp_area_matrix()`: - - sage: M=Manifold("m203") - sage: M.cusp_area_matrix(method='maximal', verified=True) - [ 27.000000? 9.0000000000?] - [9.0000000000? 27.0000000?] - - In this example, the cusp neighborhood about cusp 0 or 1 is only - embedded if and only if its area is less than sqrt(27). The cusp - neighborhood about cusp 0 is only disjoint from the one about cusp 1 - if and only if the product of their areas is less than 9. - -- Compute areas for disjoint cusp neighborhoods with - `cusp_areas()`: - - sage: M=Manifold("m203") - sage: M.cusp_areas(policy = 'unbiased', method='maximal', verified = True) - [3.00000000000?, 3.00000000000?] - - With the above parameters, the result is intrinsic to the hyperbolic - manifold with labeled cusped. - -- Find all slopes of length less or equal to 6 when measured on the - boundary of disjoint cusp neighborhoods: - - sage: M=Manifold("m203") - sage: M.short_slopes(policy = 'unbiased', method='maximal', verified = True) - [[(1, 0), ..., (1, 2)], [(1, 0), ..., (1, 2)]] - - First block has all short slopes for first cusp, …, see - `short_slopes()` - for details. - - By Agol’s and - Lackenby’s 6-Theorem any - Dehn-filling resulting in a non-hyperbolic manifold must contain one - of the above slopes. Thus, - `short_slopes()` - can be used to implement the techniques to find exceptional Dehn - surgeries (arXiv:1109.0903 and - arXiv:1310.3472). - -- An example of finding all geodesics up to length 1: - - sage: from snappy.sage_helper import RIF - sage: L = RIF(1) - sage: M = Manifold("m003") - sage: spec = M.length_spectrum_alt_gen(verified=True) - sage: n = 0 - sage: for g in spec: - ... if g.length.real() > L: - ... break # Done! All subsequent geodesics will be longer. - ... if g.length.real() < L: - ... n += 1 - ... continue - ... raise Exception("Interval too large. Increase precision.") - sage: n - 4 - -Additionally, we can compute complex intervals for the shapes that are -guaranteed to contain a true solution to the rectangular gluing -equations that is not necessarily a geometric solution (specify -`bits_prec` or `dec_prec` for higher precision intervals.): - - sage: M = Manifold("m015(3,1)") - sage: M.tetrahedra_shapes('rect', intervals=True) - [0.625222762246? + 3.177940133813?*I, - -0.0075523593782? + 0.5131157955971?*I, - 0.6515818912107? - 0.1955023488930?*I] - -This is all based on a reimplementation of -HIKMOT which -pioneered the use of interval methods for hyperbolic manifolds (also see -Zgliczynski’s -notes). It can be -used in a way very similar to HIKMOT, but uses Sage’s complex interval -types for certification. It furthermore makes use of code by Dunfield, -Hoffman, Licata. - -This verification code was contributed by Matthias Goerner. - -## Verified computation topics - -- Internals of verified computations diff --git a/apn/prompts.py b/apn/prompts.py index 4ad09cd5..484c4298 100644 --- a/apn/prompts.py +++ b/apn/prompts.py @@ -50,10 +50,11 @@ def user_prompt(path: str, token_limit: int | None, literature: bool, util_modul Your environment has the following available: * A Lean 4 toolchain with Mathlib, plus the `loogle` search CLI. * The `sage` computer algebra system (version 10), with `gp` (PARI), `gap`, `Singular`, and `maxima` also on PATH. -* `python3` with numpy, scipy, sympy, mpmath, pandas, networkx, igraph, python-flint, highspy (LP/MIP), python bindings for the solvers below (z3, cvc5, OR-Tools CP-SAT, pysat), and snappy (SnapPy, 3-manifolds). -* Solver binaries: `z3`, `cvc5`, `kissat` (SAT, DIMACS), `cryptominisat` (SAT), `csdp` (semidefinite programs), `msolve` (polynomial systems), `prover9`/`mace4` (first-order prover / countermodel finder). -* Mathematical CLI tools: `primesieve`, `primecount`, `ecm` (integer factorization), nauty's generators (`geng`, `genbg`, ...), `plantri` (planar graphs), `polymake` (polyhedral geometry), `normaliz` (rational cones), 4ti2 (lattice ideals), `lrs` (vertex enumeration), `M2` (Macaulay2, commutative algebra), `regina-python` (low-dimensional topology). -* `git`, `rg`, and `jq` +* `python3` with numpy, scipy, sympy, mpmath, pandas, networkx, igraph, python-flint, highspy (LP/MIP), cvxpy (with Clarabel), pyscipopt (SCIP, global MINLP), clingo (answer-set programming), graphillion (ZDD set families), libsemigroups_pybind11 (semigroups/automata), pymanopt (manifold optimization), pysindy (sparse dynamics identification), hypothesis (property-based testing), python bindings for z3, cvc5, OR-Tools CP-SAT, and pysat, and snappy (SnapPy, 3-manifolds). +* `julia` with OSCAR and Hecke preinstalled (Galois groups, number fields, group theory). +* Solver binaries: `z3`, `cvc5`, `kissat` (SAT, DIMACS), `cryptominisat` (SAT), `drat-trim`/`lrat-check` and `cake_lpr` (SAT proof checkers), `breakid` (CNF symmetry breaking), `smsg` (SAT-modulo-symmetries graph search), `march_cu` (cube-and-conquer splitting), `vampire` (first-order prover, finite models via --mode fmb), `eprover` (first-order prover), `prover9`/`mace4` (first-order prover / countermodel finder), `csdp` (semidefinite programs), `msolve` (polynomial systems), `clingo` (ASP), `minizinc` (constraint modeling), `berkeley-abc` (Boolean networks). +* Mathematical CLI tools: `primesieve`, `primecount`, `ecm` and `msieve` (integer factorization), `srsieve2` (k*b^n+-c sieving), `sllr64` and `pfgw64` (special-form primality proving), the nauty suite (`geng`, `genbg`, `gentreeg`, `gentourng`, `vcolg`, `shortg`, `labelg`, `showg`, `amtog`, ...), `plantri` (planar graphs), `polymake` (polyhedral geometry), `normaliz` (rational cones), 4ti2 (lattice ideals), `lrs` (vertex enumeration), `redumis` (large independent sets), `M2` (Macaulay2, commutative algebra), `regina-python` (low-dimensional topology), `topcom-*` (point-configuration triangulations), `cadabra2` (tensor algebra), `mpsolve` (certified polynomial roots), `gclc` (Euclidean geometry proving), and `/opt/walnut/walnut.sh` (Walnut: decides automatic-sequence/base-k digit statements). +* `git`, `rg`, `jq`, and `gcc`/`make` * Documentation for the less famous tools is available at `/opt/docs` Blindly searching for counterexamples using numerics is rarely a good approach. diff --git a/apn/redteam.py b/apn/redteam.py index 1ecdb274..26bdbe8e 100644 --- a/apn/redteam.py +++ b/apn/redteam.py @@ -124,7 +124,7 @@ def _apn_codebase_tar() -> bytes: root = Path(apn.__file__).parent skip_top = {"data", "__pycache__"} - skip_any = {"__pycache__", "docs"} + skip_any = {"__pycache__"} buf = io.BytesIO() with tarfile.open(fileobj=buf, mode="w:gz") as tf: for p in sorted(root.rglob("*")): diff --git a/pyproject.toml b/pyproject.toml index a7aeae7c..7a035b3b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "apn" -version = "0.1.10rc1" +version = "0.1.10rc2" description = "An Inspect implementation of the AlphaProof Nexus formal proof-search framework" license = "MIT AND Apache-2.0" license-files = ["LICENSE"] diff --git a/tests/test_agent_image.py b/tests/test_agent_image.py index e956a9ac..0a2798ed 100644 --- a/tests/test_agent_image.py +++ b/tests/test_agent_image.py @@ -23,6 +23,7 @@ from __future__ import annotations +import platform from collections.abc import AsyncIterator from contextlib import asynccontextmanager @@ -57,11 +58,19 @@ "Singular", "maxima", "z3", + "clingo", "primesieve", "primecount", "ecm", "geng", "genbg", + "gentreeg", + "gentourng", + "vcolg", + "shortg", + "labelg", + "showg", + "amtog", "normaliz", "zsolve", "lrs", @@ -72,15 +81,45 @@ "msolve", "prover9", "mace4", + "vampire", + "drat-trim", + "lrat-check", + "cake_lpr", + "breakid", + "smsg", + "march_cu", + "msieve", + "redumis", + "gclc", + # julia_build + "julia", # apt (bookworm) "polymake", "M2", "regina-python", "cryptominisat", "csdp", + "topcom-points2triangs", + "cadabra2", + "minizinc", + "berkeley-abc", + "eprover", + "mpsolve", + "java", "jq", "rg", "git", + "gcc", + "make", +] + +# The special-form primality toolchain: absent from arm64 images (local dev +# on Apple silicon); CI and production images are amd64. sllr64/pfgw64 are +# x86-64 gwnum assembly; srsieve2's makefile only knows x86 and 32-bit ARM. +BINARIES_X86_ONLY = [ + "sllr64", + "pfgw64", + "srsieve2", ] # Python modules importable from the agent's `python3` (the /opt/env python). @@ -100,24 +139,39 @@ "ortools", "pysat", # python-sat "snappy", # SnapPy + "cvxpy", + "pyscipopt", + "clingo", + "graphillion", + "libsemigroups_pybind11", + "pymanopt", + "pysindy", + "hypothesis", "sage.all", ] -# Vendored docs directories (apn/lean/docs/ -> /opt/docs/). +# Docs directories, downloaded at image build from pinned upstream sources +# (Dockerfile `docs_fetch` stage -> /opt/docs/). DOCS_DIRS = [ "loogle", - "nauty", "plantri", - "polymake", "normaliz", "4ti2", "lrslib", "msolve", "csdp", - "prover9", "regina", "snappy", "python-flint", + "sms", + "graphillion", + "breakid", + "drat-trim", + "cake_lpr", + "kamis", + "gclc", + "msieve", + "walnut", ] @@ -172,6 +226,25 @@ async def test_binary_on_path(agent_env: SandboxEnvironment, binary: str) -> Non assert code == 0, f"binary {binary!r} not on the agent's login-shell PATH" +@pytest.mark.asyncio(loop_scope="module") +@pytest.mark.parametrize("binary", BINARIES_X86_ONLY) +@pytest.mark.skipif( + platform.machine() in ("arm64", "aarch64"), + reason="x86-64-only binaries; the sandbox is built for the host arch", +) +async def test_x86_binary_on_path(agent_env: SandboxEnvironment, binary: str) -> None: + code, stdout, stderr = await _bash(agent_env, f"command -v {binary}") + assert code == 0, f"binary {binary!r} not on the agent's login-shell PATH" + + +@pytest.mark.asyncio(loop_scope="module") +async def test_walnut_launcher_present(agent_env: SandboxEnvironment) -> None: + # Walnut is a tree at /opt/walnut, not a PATH binary; the prompt advertises + # its upstream launcher path verbatim. + code, stdout, _ = await _bash(agent_env, "test -x /opt/walnut/walnut.sh") + assert code == 0, "/opt/walnut/walnut.sh missing or not executable" + + @pytest.mark.asyncio(loop_scope="module") @pytest.mark.parametrize("module", PYTHON_MODULES) async def test_python_module_imports( @@ -232,6 +305,88 @@ async def test_cpsat_solves_trivial_model(agent_env: SandboxEnvironment) -> None assert code == 0, f"CP-SAT smoke failed:\n{stderr[-2000:]}" +@pytest.mark.asyncio(loop_scope="module") +async def test_kissat_drattrim_roundtrip(agent_env: SandboxEnvironment) -> None: + """An UNSAT claim is only usable if its certificate checks: kissat emits a + DRAT proof (exit 20 = UNSAT), drat-trim verifies it (s VERIFIED).""" + code, stdout, stderr = await _bash( + agent_env, + "cd /tmp && printf 'p cnf 1 2\\n1 0\\n-1 0\\n' > smoke.cnf " + "&& kissat -q smoke.cnf smoke.drat; test $? -eq 20 " + "&& drat-trim smoke.cnf smoke.drat; rc=$?; rm -f smoke.cnf smoke.drat; exit $rc", + ) + assert code == 0, f"kissat/drat-trim roundtrip failed:\n{stdout[-1000:]}{stderr[-1000:]}" + + +@pytest.mark.asyncio(loop_scope="module") +async def test_gap_small_group(agent_env: SandboxEnvironment) -> None: + # The conda GAP ships the SmallGrp library; its absence would silently + # gut the group-theory workflow the prompt implies. + code, stdout, stderr = await _bash( + agent_env, "gap -q -c 'Print(Size(SmallGroup(64, 1)), \"\\n\"); QUIT;'", timeout=300 + ) + assert code == 0, f"gap failed:\n{stderr[-2000:]}" + # gap prints informational "#I ..." banner lines before the answer. + assert stdout.strip().splitlines()[-1] == "64", stdout[-2000:] + + +@pytest.mark.asyncio(loop_scope="module") +async def test_scip_solves_miqcp(agent_env: SandboxEnvironment) -> None: + # pyscipopt's wheel bundles libscip; max x+y s.t. x^2+y^2<=25, x integer. + script = ( + "from pyscipopt import Model\n" + "m = Model()\n" + "x = m.addVar('x', vtype='I', lb=0, ub=10)\n" + "y = m.addVar('y', lb=0, ub=5)\n" + "m.addCons(x*x + y*y <= 25)\n" + "m.setObjective(x + y, 'maximize')\n" + "m.hideOutput()\n" + "m.optimize()\n" + "assert m.getStatus() == 'optimal', m.getStatus()\n" + "assert abs(m.getObjVal() - 7) < 1e-4, m.getObjVal()\n" + ) + code, stdout, stderr = await _bash( + agent_env, f"python3 - <<'EOF'\n{script}EOF", timeout=300 + ) + assert code == 0, f"SCIP smoke failed:\n{stderr[-2000:]}" + + +@pytest.mark.asyncio(loop_scope="module") +async def test_vampire_refutes(agent_env: SandboxEnvironment) -> None: + code, stdout, stderr = await _bash( + agent_env, + "printf 'fof(a, axiom, p).\\nfof(c, conjecture, p).\\n' " + "| vampire --time_limit 30", + ) + assert code == 0, f"vampire failed:\n{stderr[-2000:]}\n{stdout[-2000:]}" + assert "Refutation" in stdout + + +@pytest.mark.asyncio(loop_scope="module") +async def test_walnut_decides_trivial_property(agent_env: SandboxEnvironment) -> None: + # Walnut ships the Thue-Morse word T; a universally true statement about + # it must come back TRUE (proves the jar + word automata actually load). + code, stdout, stderr = await _bash( + agent_env, + "cd /opt/walnut && printf 'eval smoketest \"?msd_2 An T[n]=T[n]\";\\nexit;\\n' | ./walnut.sh", + timeout=300, + ) + assert code == 0, f"walnut failed:\n{stderr[-2000:]}\n{stdout[-2000:]}" + assert "TRUE" in stdout, f"expected TRUE:\n{stdout[-2000:]}" + + +@pytest.mark.asyncio(loop_scope="module") +async def test_julia_oscar_loads(agent_env: SandboxEnvironment) -> None: + # The baked depot must load offline with no re-precompilation surprises. + code, stdout, stderr = await _bash( + agent_env, + "julia -e 'using Oscar; println(order(symmetric_group(4)))'", + timeout=600, + ) + assert code == 0, f"julia/Oscar failed:\n{stderr[-2000:]}" + assert stdout.strip().endswith("24") + + @pytest.mark.asyncio(loop_scope="module") async def test_loogle_finds_nat_prime(agent_env: SandboxEnvironment) -> None: # Upstream's documented invocation (vendored at /opt/docs/loogle): from diff --git a/tests/test_tools.py b/tests/test_tools.py index d17241d4..97a6d030 100644 --- a/tests/test_tools.py +++ b/tests/test_tools.py @@ -23,14 +23,20 @@ def test_user_prompt_references_path() -> None: def test_user_prompt_mentions_environment_tools() -> None: # Sentinel tools from each layer of the agent image's compute stack: the - # lean layer (loogle), the conda env (sage, z3), the source-built solvers - # (kissat), the goal-state idiom, and the vendored docs location. + # lean layer (loogle), the conda env (sage, z3, clingo), the pip layer + # (pyscipopt), the source-built/release solvers (kissat, vampire), the + # julia stack (Oscar), Walnut's launcher path, and the docs location. rendered = user_prompt(PROOF_PATH, token_limit=None, literature=False, util_module=UTIL_MODULE) assert "Lean 4" in rendered assert "loogle" in rendered assert "sage" in rendered assert "z3" in rendered + assert "clingo" in rendered + assert "pyscipopt" in rendered assert "kissat" in rendered + assert "vampire" in rendered + assert "OSCAR" in rendered + assert "/opt/walnut/walnut.sh" in rendered assert "/opt/docs" in rendered # The pantograph toolchain is gone from the image; the prompt must not # advertise it. diff --git a/uv.lock b/uv.lock index 03288fe9..18db91bd 100644 --- a/uv.lock +++ b/uv.lock @@ -182,7 +182,7 @@ wheels = [ [[package]] name = "apn" -version = "0.1.10rc1" +version = "0.1.10rc2" source = { editable = "." } [package.dev-dependencies] From 52da9fd9a98f43e5cb1fb70ac7bdb80a3aa07074 Mon Sep 17 00:00:00 2001 From: tadamcz Date: Sat, 29 Aug 2026 02:03:13 +0100 Subject: [PATCH 6/7] Bump version to 0.1.10rc3 --- apn/__init__.py | 2 +- pyproject.toml | 2 +- uv.lock | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apn/__init__.py b/apn/__init__.py index 398df821..27f6d21e 100644 --- a/apn/__init__.py +++ b/apn/__init__.py @@ -1,4 +1,4 @@ __all__ = ["__version__"] -__version__ = "0.1.10rc2" +__version__ = "0.1.10rc3" diff --git a/pyproject.toml b/pyproject.toml index 7a035b3b..c0d6684a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "apn" -version = "0.1.10rc2" +version = "0.1.10rc3" description = "An Inspect implementation of the AlphaProof Nexus formal proof-search framework" license = "MIT AND Apache-2.0" license-files = ["LICENSE"] diff --git a/uv.lock b/uv.lock index 18db91bd..f3e86349 100644 --- a/uv.lock +++ b/uv.lock @@ -182,7 +182,7 @@ wheels = [ [[package]] name = "apn" -version = "0.1.10rc2" +version = "0.1.10rc3" source = { editable = "." } [package.dev-dependencies] From 2ee9cdd3e73d278360d3b98d70ec96a7a13623a6 Mon Sep 17 00:00:00 2001 From: tadamcz Date: Sat, 29 Aug 2026 02:10:45 +0100 Subject: [PATCH 7/7] Fetch LLR over plain HTTP (its host serves no TLS; sha256-pinned) --- apn/lean/Dockerfile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/apn/lean/Dockerfile b/apn/lean/Dockerfile index 8c16ce77..14f937b6 100644 --- a/apn/lean/Dockerfile +++ b/apn/lean/Dockerfile @@ -490,7 +490,8 @@ RUN if [ "$(uname -m)" = x86_64 ]; then \ && rm -rf /tmp/mtsieve; \ fi RUN if [ "$(uname -m)" = x86_64 ]; then \ - curl -sSfL -o /tmp/llr.zip "https://jpenne.free.fr/llr4/llr${LLR_VERSION}slinux64.zip" \ + # jpenne.free.fr is HTTP-only; integrity comes from the sha256 pin. + curl -sSfL -o /tmp/llr.zip "http://jpenne.free.fr/llr4/llr${LLR_VERSION}slinux64.zip" \ && echo "b92424d85d0d37788bb33613ec1af2b6d5cb1f5ce37be5ed062b0aad604a6ab3 /tmp/llr.zip" | sha256sum -c - \ && unzip -q /tmp/llr.zip -d /tmp/llr \ && install -m 755 "$(find /tmp/llr -type f -name sllr64)" /out/bin/sllr64 \