From 54209f35ccafee5499df764c999d5f071c09e96f Mon Sep 17 00:00:00 2001 From: David Sagan Date: Fri, 13 Dec 2024 15:28:10 -0500 Subject: [PATCH 1/4] Doc reorg. --- .gitignore | 2 + README.md | 5 +++ .../contributing.md | 2 +- .../doc_editing_setup.md | 4 +- GOVERNANCE.md => front_matter/governance.md | 0 front_matter/introduction.md | 39 +++++++++++++++++++ .../pull_request_template.md | 0 myst.yml | 18 ++++++--- section_example.md | 12 ------ standard/{standard.md => introduction.md} | 2 +- 10 files changed, 63 insertions(+), 21 deletions(-) create mode 100644 .gitignore rename CONTRIBUTING.md => front_matter/contributing.md (98%) rename section_documentation.md => front_matter/doc_editing_setup.md (78%) rename GOVERNANCE.md => front_matter/governance.md (100%) create mode 100644 front_matter/introduction.md rename pull_request_template.md => front_matter/pull_request_template.md (100%) delete mode 100644 section_example.md rename standard/{standard.md => introduction.md} (99%) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..eac0968 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# MyST build outputs +_build diff --git a/README.md b/README.md index a053280..e2a9182 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,11 @@ An effort to create a standard to promote lattice information exchange for parti As part of this effort, we focus on the physical layout and properties of a machine. This excludes description of tracking of particles including collective effects. +## Participation + +There are weekly (more or less) meetings to discuss development of the lattice standard. +To participate in the creation of the lattice standard, please contact [Jean-Luc Vay](https://https://github.com/jlvay) to be put on the mailing list. + ## Roadmap 1. **Reach out to the community (continuous)** diff --git a/CONTRIBUTING.md b/front_matter/contributing.md similarity index 98% rename from CONTRIBUTING.md rename to front_matter/contributing.md index acef2ea..bbbf0f6 100644 --- a/CONTRIBUTING.md +++ b/front_matter/contributing.md @@ -1,4 +1,4 @@ -# Contributing +# How to Contribute Follow these steps **only once**: 1. Go to https://github.com/campa-consortium/lattice-standard. diff --git a/section_documentation.md b/front_matter/doc_editing_setup.md similarity index 78% rename from section_documentation.md rename to front_matter/doc_editing_setup.md index 8fc1ec0..9f5e677 100644 --- a/section_documentation.md +++ b/front_matter/doc_editing_setup.md @@ -1,4 +1,6 @@ -# Documentation +# Documentation Editing Setup + +The documentation uses the [MyST](https://myst-parser.readthedocs.io/en/latest/) markup language. Install the following packages within an existing conda environment: ```{code} bash diff --git a/GOVERNANCE.md b/front_matter/governance.md similarity index 100% rename from GOVERNANCE.md rename to front_matter/governance.md diff --git a/front_matter/introduction.md b/front_matter/introduction.md new file mode 100644 index 0000000..e1d96ea --- /dev/null +++ b/front_matter/introduction.md @@ -0,0 +1,39 @@ +# Accelerator Lattice Standard + +This standard is +an effort to create a standard to promote lattice information exchange for particle accelerators. + +## Scope + +The standard focusus on the physical layout and properties of a machine. +This excludes description of tracking of particles including collective effects. + +## Participation + +There are weekly (more or less) meetings to discuss development of the lattice standard. +To participate in the creation of the lattice standard, please contact [Jean-Luc Vay](https://https://github.com/jlvay) to be put on the mailing list. + +## Roadmap + +1. **Reach out to the community (continuous)** + +2. **Request for documentation:** + * Goal: document how various accelerator modeling codes already do for their lattices. + * Organizers: Create a template. + * element parameters + * lines/beamlines: how are elements distributed + * example of a facility/lattice + * Community: to fill out a template per existing code. + +3. **Request for proposals:** how would we like to describe lattices and individual elements in terms of physical line & element properties? + * Goal: write down as text document (standard) + * use a simple bullet point document, e.g., with name of element, purpose, properties and alternates + * Form community consensus on: + * elements: which properties to put in the standard we are developing; which alternate descriptions do we need for the same element? + * lines/beamlines: which descriptions (e.g., sub-lines, channels/repetitions, line order inversion, physical line inversion, constants/variables to scale lines, etc.) do we need in the standard we are developing or which ones belong in implementations + +4. **Request for proposals:** how would we like to store & exchange lattices in the 21st century? + * Goal: document advise to implementers. + * How can we programming language agnostic store and exchange lattices? + * examples for storage formats: TOML, YAML, JSON, XML, ... (with the right framework, one can support them all) + * examples for frameworks (import/export/validation): [pydantic](https://docs.pydantic.dev) (Python), [StructTypes.jl](https://github.com/JuliaData/StructTypes.jl)/[Parameters.jl](https://github.com/mauro3/Parameters.jl) in Julia, etc. diff --git a/pull_request_template.md b/front_matter/pull_request_template.md similarity index 100% rename from pull_request_template.md rename to front_matter/pull_request_template.md diff --git a/myst.yml b/myst.yml index 12d7e50..9173f31 100644 --- a/myst.yml +++ b/myst.yml @@ -2,17 +2,23 @@ version: 1 project: id: 04669581-a5a2-47e4-8d37-bf222bc14229 - title: Accelerator Lattice Standard + title: 'Particle Accelerator Description Standard' # description: # keywords: [] # authors: [] github: https://github.com/campa-consortium/lattice-standard toc: - - file: 'README.md' - - file: 'GOVERNANCE.md' - - file: 'CONTRIBUTING.md' - - file: 'section_documentation.md' - - file: 'section_example.md' + - file: 'front_matter/introduction.md' + - title: 'Front Matter' + children: + - file: 'front_matter/organization.md' + - file: 'front_matter/governance.md' + - file: 'front_matter/contributing.md' + - file: 'front_matter/doc_editing_setup.md' + - title: 'Lattice Standard' + children: + - file: 'standard/introduction.md' + - file: 'standard/element_parameter.md' site: template: book-theme domains: diff --git a/section_example.md b/section_example.md deleted file mode 100644 index fefeaf6..0000000 --- a/section_example.md +++ /dev/null @@ -1,12 +0,0 @@ -# Math - -Math can be rendered inline, as in $Ax=b$, or in equation blocks: -$$ - \label{kljs} - \begin{aligned} - KL\left(\hat{y} || y\right) & = \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\ - JS\left(\hat{y} || y\right) & = \frac{1}{2}\left(KL\left(y||\frac{y+\hat{y}}{2}\right) + KL\left(\hat{y}||\frac{y+\hat{y}}{2}\right)\right) - \end{aligned} -$$ - -Equations, such as [](#kljs), can be cross-referenced. Subequations with multiple labels to be understood yet. diff --git a/standard/standard.md b/standard/introduction.md similarity index 99% rename from standard/standard.md rename to standard/introduction.md index 39adf4c..54489c2 100644 --- a/standard/standard.md +++ b/standard/introduction.md @@ -1,4 +1,4 @@ -# Accelerator Lattace Standard +# Introduction ## Overview From c5ca553ddb4059d3bf22dc9c3fb90fde6142038c Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 18 Dec 2024 12:39:05 -0500 Subject: [PATCH 2/4] Update doc_editing_setup.md --- front_matter/doc_editing_setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/front_matter/doc_editing_setup.md b/front_matter/doc_editing_setup.md index 9f5e677..067ce2f 100644 --- a/front_matter/doc_editing_setup.md +++ b/front_matter/doc_editing_setup.md @@ -1,6 +1,6 @@ # Documentation Editing Setup -The documentation uses the [MyST](https://myst-parser.readthedocs.io/en/latest/) markup language. +The documentation uses the [MyST](https://mystmd.org/) markup language. Install the following packages within an existing conda environment: ```{code} bash From 2b6d2eac888b912277f54dc9fffed6763c595f7d Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 18 Dec 2024 12:39:54 -0500 Subject: [PATCH 3/4] Update introduction.md --- front_matter/introduction.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/front_matter/introduction.md b/front_matter/introduction.md index e1d96ea..951a448 100644 --- a/front_matter/introduction.md +++ b/front_matter/introduction.md @@ -1,7 +1,6 @@ # Accelerator Lattice Standard -This standard is -an effort to create a standard to promote lattice information exchange for particle accelerators. +This standard is an effort to create a standard to promote lattice information exchange for particle accelerators. ## Scope From d0cb56cddd652920498b46b96554433d170e43ee Mon Sep 17 00:00:00 2001 From: David Sagan Date: Wed, 18 Dec 2024 12:40:25 -0500 Subject: [PATCH 4/4] Update introduction.md --- front_matter/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/front_matter/introduction.md b/front_matter/introduction.md index 951a448..1f1606c 100644 --- a/front_matter/introduction.md +++ b/front_matter/introduction.md @@ -4,7 +4,7 @@ This standard is an effort to create a standard to promote lattice information e ## Scope -The standard focusus on the physical layout and properties of a machine. +The standard focuses on the physical layout and properties of a machine. This excludes description of tracking of particles including collective effects. ## Participation