{"id":13838288,"url":"https://github.com/math-comp/hierarchy-builder","last_synced_at":"2025-04-05T12:05:10.967Z","repository":{"id":40469548,"uuid":"180381692","full_name":"math-comp/hierarchy-builder","owner":"math-comp","description":"High level commands to declare a hierarchy based on packed classes","archived":false,"fork":false,"pushed_at":"2025-02-25T16:04:07.000Z","size":10916,"stargazers_count":97,"open_issues_count":100,"forks_count":23,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-29T11:06:45.117Z","etag":null,"topics":["coq","elpi","mathcomp"],"latest_commit_sha":null,"homepage":"","language":"Coq","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/math-comp.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-09T14:10:53.000Z","updated_at":"2025-02-25T16:04:11.000Z","dependencies_parsed_at":"2023-11-07T01:08:12.509Z","dependency_job_id":"fb12fe06-593b-4dbb-a570-55a1b9dfde01","html_url":"https://github.com/math-comp/hierarchy-builder","commit_stats":{"total_commits":894,"total_committers":16,"mean_commits":55.875,"dds":"0.40604026845637586","last_synced_commit":"cbc149f1a24617da17a8c62e346e11ed103969bb"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/math-comp%2Fhierarchy-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/math-comp%2Fhierarchy-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/math-comp%2Fhierarchy-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/math-comp%2Fhierarchy-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/math-comp","download_url":"https://codeload.github.com/math-comp/hierarchy-builder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332602,"owners_count":20921853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coq","elpi","mathcomp"],"created_at":"2024-08-04T15:01:48.602Z","updated_at":"2025-04-05T12:05:10.947Z","avatar_url":"https://github.com/math-comp.png","language":"Coq","funding_links":[],"categories":["Projects","Prolog"],"sub_categories":["Plugins"],"readme":"[![Actions Status](https://github.com/math-comp/hierarchy-builder/workflows/CI/badge.svg)](https://github.com/math-comp/hierarchy-builder/actions)\n[![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://coq.zulipchat.com/#narrow/stream/237868-Hierarchy-Buidlder)\n\n# Hierarchy Builder\n\nHierarchy Builder (HB) provides high level commands to declare a hierarchy of algebraic structure\n(or interfaces if you prefer the glossary of computer science) for the Coq system.\n\nGiven a structure one can develop its theory, and that theory becomes automatically applicable to\nall the examples of the structure. One can also declare alternative interfaces, for convenience\nor backward compatibility, and provide glue code linking these interfaces to the structures part of\nthe hierarchy.\n\nHB commands compile down to Coq modules, sections, records, coercions, canonical structure instances\nand notations following the *packed classes* discipline which is at the core of the [Mathematical\nComponents](https://github.com/math-comp/math-comp) library. All that complexity is hidden behind\na few concepts and a few declarative Coq commands.\n\n## Example\n\n```coq\nFrom HB Require Import structures.\nFrom Coq Require Import ssreflect ZArith.\n\nHB.mixin Record IsAddComoid A := {\n  zero : A;\n  add : A -\u003e A -\u003e A;\n  addrA : forall x y z, add x (add y z) = add (add x y) z;\n  addrC : forall x y, add x y = add y x;\n  add0r : forall x, add zero x = x;\n}.\n\nHB.structure Definition AddComoid := { A of IsAddComoid A }.\n\nNotation \"0\" := zero.\nInfix \"+\" := add.\n\nCheck forall (M : AddComoid.type) (x : M), x + x = 0.\n```\n\nThis is all we need to do in order to declare the `AddComoid` structure\nand write statements in its signature.\n\nWe proceed by declaring how to obtain an Abelian group out of the\nadditive, commutative, monoid.\n\n```coq\nHB.mixin Record IsAbelianGrp A of IsAddComoid A := {\n  opp : A -\u003e A;\n  addNr : forall x, opp x + x = 0;\n}.\n\nHB.structure Definition AbelianGrp := { A of IsAbelianGrp A \u0026 IsAddComoid A }.\n\nNotation \"- x\" := (opp x).\n```\n\nAbelian groups feature the operations and properties given by the\n`IsAbelianGrp` mixin (and its dependency `IsAddComoid`).\n\n```coq\nLemma example (G : AbelianGrp.type) (x : G) : x + (- x) = - 0.\nProof. by rewrite addrC addNr -[LHS](addNr zero) addrC add0r. Qed.\n```\n\nWe proceed by showing that `Z` is an example of both structures, and use\nthe lemma just proved on a statement about `Z`.\n\n```coq\nHB.instance Definition Z_CoMoid :=\n  IsAddComoid.Build Z 0%Z Z.add Z.add_assoc Z.add_comm Z.add_0_l.\n \nHB.instance Definition Z_AbGrp :=\n  IsAbelianGrp.Build Z Z.opp Z.add_opp_diag_l.\n\nLemma example2 (x : Z) : x + (- x) = - 0.\nProof. by rewrite example. Qed.\n```\n\n## Documentation\n\nThis [paper](https://hal.inria.fr/hal-02478907) describes the language\nin details, and the corresponding talk [is available on youtube](https://www.youtube.com/watch?v=F6iRaTlQrlo).\nThe [wiki](https://github.com/math-comp/hierarchy-builder/wiki) gathers some\ntricks and FAQs. If you want to work on the implementation of HB, this\n[recorded hacking session](https://www.youtube.com/watch?v=gmaJjCbzqO0) may be relevant to you.\n\n### Installation \u0026 availability\n\n\u003cdetails\u003e\u003csummary\u003e(click to expand)\u003c/summary\u003e\u003cp\u003e\n\n- You can install HB via OPAM\n\n```shell\nopam repo add coq-released https://coq.inria.fr/opam/released\nopam install coq-hierarchy-builder\n```\n\n- You can use it in nix with the attribute `coqPackages_8_XX.hierarchy-builder` e.g.\n  via `nix-shell -p coq_8_13 -p coqPackages_8_13.hierarchy-builder`\n \n\u003c/p\u003e\u003c/details\u003e\n\n### Key concepts\n\n\u003cdetails\u003e\u003csummary\u003e(click to expand)\u003c/summary\u003e\u003cp\u003e\n\n- a *mixin* is a bare bone building block of the hierarchy, it packs operations\n  and axioms.\n\n- a *factory* is a package of operations and properties that is elaborated by\n  HB to one or more mixin. A mixin is hence a trivial factory.\n\n- a *structure* is declared by attaching zero or more factories to a type.\n\n- a *builder* is a user provided piece of code capable of\n  building one or more mixins from a factory.\n\n- an *instance* is an example of a structure: it provides all operation and\n  fulfills all axioms.\n\n\u003c/p\u003e\u003c/details\u003e\n\n### The commands of HB\n\n\u003cdetails\u003e\u003csummary\u003e(click to expand)\u003c/summary\u003e\u003cp\u003e\n\n- HB core commands:\n  - `HB.mixin` declares a mixin,\n  - `HB.structure` declares a structure,\n  - `HB.factory` declares a factory,\n  - `HB.builders` and `HB.end` declare a set of builders,\n  - `HB.instance` declares a structure instance,\n  - `HB.declare` declares a context with parameters, key and mixins.\n  - `HB.saturate` reconsiders all mixin instances to see if some newly declared\n    structure can be inhabited\n\n- HB core tactic-in-term:\n  - `HB.pack` to synthesize a structure instance in the middle of a term.\n\n- HB utility commands:\n  - `HB.export` exports a module and schedules it for re-export\n  - `HB.reexport` exports all modules, instances and constants scheduled for\n    re-export\n  - `HB.lock` locks a definition behind an opaque symbol and an unfolding\n    equation using Coq module system\n\n- HB queries:\n  - `HB.about` is similar to `About` but prints more info on HB structures, like\n    the known instances and where they are declared\n  - `HB.locate` is similar to `Locate`, prints file name and line of any global\n    constant synthesized by HB\n  - `HB.graph` prints the structure hierarchy to a dot file\n  - `HB.howto` prints sequences of factories to equip a type with a given structure\n\n- HB debug commands:\n  - `HB.status` dumps the contents of the hierarchy (debug purposes)\n  - `HB.check` is similar to `Check` (testing purposes)\n\nThe documentation of all commands can be found in the comments of\n[structures.v](HB/structures.v), search for `Elpi Command` and you will\nfind them. All commands can be prefixed with the attribute `#[verbose]`\nto get an idea of what they are doing.\n\nFor debugging and teaching purposes, passing the attributes\n`#[log]` or `#[log(raw)]` to a HB command prints Coq commands which are\n*almost* equivalent to its effect. Hence, copy-pasting the displayed commands into\nyour source file is not expected to work, and we strongly recommend\nagainst it.\n\n\u003c/p\u003e\u003c/details\u003e\n\n### Demos\n\n\u003cdetails\u003e\u003csummary\u003e(click to expand)\u003c/summary\u003e\u003cp\u003e\n\n- [demo1](examples/demo1/) and [demo3](examples/demo3/) declare and evolve a hierarchy up to\n  rings with various clients that are tested not to break when the hierarchy\n  evolves\n- [demo2](examples/demo2/) describes the subtle triangular interaction between groups,\n  topological space and uniform spaces. Indeed, 1. all uniform spaces induce a\n  topology, which makes them topological spaces, but 2. all topological groups\n  (groups that are topological spaces such that the addition and opposite are\n  continuous) induce a uniformity, which makes them uniform spaces. We solve\n  this seamingly mutual dependency using HB.\n\n\u003c/p\u003e\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmath-comp%2Fhierarchy-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmath-comp%2Fhierarchy-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmath-comp%2Fhierarchy-builder/lists"}