diff --git a/README.md b/README.md index 10f5013..870c723 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,17 @@ every participant: people and agents, with a window or without. BeamletOpticsGUI top of it. An agent needs no GUI: it works with BeamletOptics and BeamletOpticsProjects only. Each package ships its own agent skill (`install_agent_skill()`). +## Installation + +BeamletOpticsProjects is not in the General registry yet. Install it, and BeamletOptics in the +version it is developed against, from their repositories: + +```julia +using Pkg +Pkg.add([PackageSpec(url = "https://github.com/StackEnjoyer/BeamletOptics.jl", rev = "master"), + PackageSpec(url = "https://github.com/StackEnjoyer/BeamletOpticsProjects.jl", rev = "main")]) +``` + ## A project ```text diff --git a/docs/src/index.md b/docs/src/index.md index 248ab2e..1eb64ba 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -25,6 +25,17 @@ every participant: people and agents, with a window or without. BeamletOpticsGUI top of it. An agent needs no GUI: it works with BeamletOptics and BeamletOpticsProjects only. Each package ships its own agent skill (`install_agent_skill()`). +## Installation + +BeamletOpticsProjects is not in the General registry yet. Install it, and BeamletOptics in the +version it is developed against, from their repositories: + +```julia +using Pkg +Pkg.add([PackageSpec(url = "https://github.com/StackEnjoyer/BeamletOptics.jl", rev = "master"), + PackageSpec(url = "https://github.com/StackEnjoyer/BeamletOpticsProjects.jl", rev = "main")]) +``` + ## A project ```text diff --git a/skills/beamletopticsprojects/FORMAT.md b/skills/beamletopticsprojects/FORMAT.md index 35c6743..19d60f4 100644 --- a/skills/beamletopticsprojects/FORMAT.md +++ b/skills/beamletopticsprojects/FORMAT.md @@ -11,17 +11,36 @@ One line per entry; components first, then sources, then groups, then systems: - The name after `@component`/`@source`/`@group`/`@system` is the readable **id** (`L1`, `M2`, `D3`, `BS1`, `B1`, `G1`, `S1`: a prefix of the family and a number, see `id_prefix`). It is unique and stays; never - rename an id. Give a new line the next free number of its prefix (`next_id(p, "L")`). + rename an id. Give a new line the next free number of its prefix (`next_id(p, "L")`). The prefix + comes from the type that the code builds, and the number counts over the whole project, so + `add!` may give `M3` where you expected `M1`: use the id that it returns. + + | Built object | Prefix | + |---|---| + | `Lens`, `DoubletLens`, `TripletLens` | `L` | + | prisms | `P` | + | mirrors and other reflective optics | `M` | + | detectors | `D` | + | beamsplitters | `BS` | + | sources (beams and beam groups) | `B` | + | groups | `G` | + | systems | `S` | + | anything else | `X` | + + A package with own component types may add prefixes (methods of `id_prefix`). - `label = "…"` is the name that people see and change in the GUI; optional. When a person names an - object ("the collimator"), find its id by the label (`look(p)` shows the labels). + object ("the collimator"), find its id by the label (`look(p)` shows the labels). Name it by what + the object does, not by an id: a label "BS1 split" contradicts the window when the id became + `BS2`. - `uid = "…"` (always last) is the machine id by which the GUI recognizes the line. Never change or copy it; a new line has no `uid`, it gets one when the project is saved. - The right-hand side is any expression that builds a BeamletOptics component, group or source, also a call of a function of `src/.jl` (its exported names). SI units: m, wavelengths in m. For an own type with a method of `constructor_code`, the window writes this expression anew from that method when a person changes the shape on its card (see "Own code" in `SKILL.md`). -- `pos` is the absolute position (m), `rot` the rotation since construction in degrees: first about - the global x-axis, then y, then z. Both are optional. +- `pos` is the absolute position (m), `rot` the rotation since construction in **degrees** (unlike + BeamletOptics, whose rotations take radians): first about the global x-axis, then y, then z. Both + are optional. - `catalog = (...)` belongs to the GUI (its page "Edit"); delete it when you change the constructor. - `@system`: members are components; a component may be in several systems, a source in at most one. `static = true` makes a `StaticSystem`. Each system is traced on its own (`trace(p, :S1)`); a detector that is in several systems is the exception in the window, which adds up their hits. diff --git a/skills/beamletopticsprojects/SKILL.md b/skills/beamletopticsprojects/SKILL.md index 0bd2337..d963b20 100644 --- a/skills/beamletopticsprojects/SKILL.md +++ b/skills/beamletopticsprojects/SKILL.md @@ -20,10 +20,13 @@ When this Skill is active: `Pkg.activate(".")`). - **Check before you change the project:** `check_versions(".")` compares the versions that the project file records with those of the environment (`look(p)` shows them too). Tell the person - about `:older` (`Pkg.update("X")`) and `:missing` (`Pkg.add("X")`). - - **No environment yet:** if `@bmo-agent` does not exist, ask the person whether to create it - (`julia --project=@bmo-agent -e 'using Pkg; Pkg.add(["BeamletOptics", "BeamletOpticsProjects"])'`, - plus the packages under `[packages]`) or which environment to use instead. Never guess a path. + about `:older` (`Pkg.update("X")`) and `:missing` (`Pkg.add("X")`, for BeamletOpticsProjects + the line below). + - **No environment yet:** if `@bmo-agent` does not exist, ask the person whether to create it or + which environment to use instead. Never guess a path. BeamletOpticsProjects is not in the + General registry yet, so both packages come from their repositories (plus the packages under + `[packages]`): + `julia --project=@bmo-agent -e 'using Pkg; Pkg.add([PackageSpec(url = "https://github.com/StackEnjoyer/BeamletOptics.jl", rev = "master"), PackageSpec(url = "https://github.com/StackEnjoyer/BeamletOpticsProjects.jl", rev = "main")])'` - **Change an environment only after the person agreed:** adding or updating packages compiles them again and changes everything else that uses the environment; say so when you ask. - **The optics comes from the `beamletoptics` skill** (units, +y optical axis, constructors, @@ -91,7 +94,8 @@ Bench/ - `id = add!(".", "RoundPlanoMirror(0.0254, 0.006)"; pos = (0.1, 0.2, 0), rot = (0, 0, 45), label = "fold", systems = [:S1], by = "claude")`: picks the next free id of its prefix in the same write (no other participant can take it meanwhile) and returns it; a source goes into - the `sources` of one system. + the `sources` of one system. `pos` is in m, `rot` in degrees (not radians as in + BeamletOptics); the prefixes of the ids are listed in `FORMAT.md`. - `set!(".", :L9; pos, rot, code, label, by)` changes only the given fields of a line (a group: its label; move groups with `move!`). - `move!(".", [:G1, :FIOS1]; offset = (0.3, 0, 0), rot = (0, 0, 10), pivot = :center, by)` moves @@ -212,7 +216,9 @@ The windows show every participant at the object it works on, people and agents - `announce(".", name = "claude", doing = "aligning L2", selected_id = "L2")` writes your presence file `.bmo/presence-@agent.toml` (see the docstring of `announce` for its fields). `name` is your id and must be unique among the participants (`"claude-w1"` for a worker of a team): the same - `name` is the same file. Call it again when you go to another object. After you wrote the files, + `name` is the same file. `selected_id` places your `doing` at that object in the windows; + without it, the windows show it in a corner of the view. Call it again when you go to another + object. After you wrote the files, call it with `wrote = true`: only then it publishes the stamp of the files (`written`), by which the windows name you as the writer of a change, also if they merged the change before your call; without `wrote = true` the `written` of the file before is kept. diff --git a/src/New.jl b/src/New.jl index 5ad93a2..2b3e943 100644 --- a/src/New.jl +++ b/src/New.jl @@ -187,7 +187,10 @@ _agents_template(name, marker) = """ ```julia # julia --project=@bmo-agent, once, after the person agreed using Pkg - Pkg.add(["BeamletOptics", "BeamletOpticsProjects"]) # and the packages under [packages] + # BeamletOpticsProjects is not in the General registry yet: both from their repositories + Pkg.add([PackageSpec(url = "https://github.com/StackEnjoyer/BeamletOptics.jl", rev = "master"), + PackageSpec(url = "https://github.com/StackEnjoyer/BeamletOpticsProjects.jl", rev = "main")]) + # and the packages under [packages] ``` ## Check