gac berninaandClaude Sonnet 5
cadfcd2667
CLI: eco --ui {shell,lab,voila,desktop} -> subcommands eco {console,desktop,
webapp,jupyterlab}, console being the default (bare `eco` == `eco console`).
desktop's -s/--scope has no forced default any more: without it you get a
plain embedded Qt console with no Namespace launcher panel, instead of
silently defaulting to bernina. Both desktop and jupyterlab get a
--console/--no-console flag (console on by default). jupyterlab, when given
-s, now registers a real eco-<scope> Jupyter kernel (IPython profile startup
file + kernelspec, regenerated each launch) and makes it JupyterLab's
default kernel, then opens a real `jupyter console` on it in the launching
terminal -- so a fresh Console/Notebook opened from JupyterLab's own
launcher gets eco.<scope> preloaded too, not just one pre-built notebook.
Also added --set-rcfile [PATH] to persist the current invocation into an
.ecorc instead of launching.
Real bug found and fixed: Namespace.append_obj writes constructed/lazy
device objects onto sys.modules[root_module] (the scope module, e.g.
eco.bernina), not onto the Namespace instance itself -- the instance only
tracks name -> state bookkeeping (lazy_items/failed_items/initialized_items).
eco.widgets.desktop_app's launcher panel and console-namespace-population
both assumed `getattr(namespace, name)` worked, which silently raised
AttributeError for every single namespace entry -- opening or initializing
anything from the desktop launcher failed outright. Added
Namespace.resolve_item() as the canonical fix (the lazy-or-failed-or-
initialized dict chain reinitialize() itself already used internally) and
build_namespace_vars() (mirrors `from eco.<scope> import *` -- bare names
like mono/att, not just a `namespace` variable) for both the in-process and
subprocess console-kernel paths.
Also ported this same fix to eco.widgets.widget_tray (the ipywidgets
dashboard backing webapp/jupyterlab), replacing the old status_collection-
based member dropdown (initialized-only, no lazy/failed visibility) with a
NamespaceLauncherWidget matching desktop's launcher: browse every
registered name including lazy/failed ones, click to initialize+open.
New: a Required column/checkbox (Namespace.required_names()) in both
launchers -- desktop's Qt _NamespaceLauncher (QListWidget -> QTableWidget,
Name + Required columns) and the new ipywidgets NamespaceLauncherWidget.
Verified via eco-dev across all four subcommands against the real bernina
scope (shell/console, desktop with and without -s, webapp, jupyterlab
including the registered-kernel mechanism via a live jupyter_client
KernelManager), plus the full test suite (44/44 in test_desktop_app.py,
323/325 overall -- the 2 failures are pre-existing in
test_config_lazy_init.py, unrelated to any of this).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
135 lines
4.5 KiB
Markdown
135 lines
4.5 KiB
Markdown
# Installation
|
|
|
|
## From the beamline environment
|
|
|
|
At SwissFEL, eco is normally already available inside the beamline conda
|
|
environments. The `eco` command launches an interactive session for a given
|
|
instrument:
|
|
|
|
```bash
|
|
eco -s bernina
|
|
```
|
|
|
|
Run `eco --help` for the full list of options.
|
|
|
|
This opens an IPython session with the scope imported and `pylab`-style
|
|
plotting ready to go — equivalent to
|
|
`ipython --profile=eco --no-banner -i -c "run <eco>/startup_inline.py -l -s bernina"`.
|
|
|
|
Defaults — scope, IPython profile, lazy initialisation, which subcommand runs
|
|
by default — do not need to be typed every time. They can be set once in an
|
|
`.ecorc` file, which is looked up as `$ECORC`, then `./.ecorc`, then
|
|
`~/.ecorc`; any setting it provides can still be overridden on the command
|
|
line, e.g. `eco -s alvra` or `eco --no-lazy`. With an `.ecorc` in place, a bare
|
|
`eco` just works:
|
|
|
|
```ini
|
|
[eco]
|
|
command = console
|
|
scope = bernina
|
|
profile = eco
|
|
lazy = true
|
|
```
|
|
|
|
`--set-rcfile [PATH]` writes exactly what you typed on that command line into
|
|
such a file (`~/.ecorc` by default) and exits instead of launching, e.g.
|
|
`eco -s alvra --set-rcfile`.
|
|
|
|
Besides the default `console` subcommand (the IPython shell), three others
|
|
start a different front end:
|
|
|
|
```bash
|
|
eco desktop -s bernina # Qt workbench: embedded console + a device browser panel
|
|
eco jupyterlab -s bernina # JupyterLab, plus a real jupyter console with the scope preloaded
|
|
eco webapp -s bernina # serve the eco dashboard notebook as a read-only Voila page
|
|
```
|
|
|
|
`desktop`/`jupyterlab`/`webapp` are optional — they are not required to use
|
|
eco, only installed on demand (e.g. `conda install jupyterlab` / `voila`, or
|
|
`pip install eco[gui]` for the desktop UI's Qt console).
|
|
|
|
**Optional — manual import.** If you are working from an uninstalled source
|
|
checkout (see *From source* below), or want to import eco directly inside a
|
|
notebook instead of going through the launcher, the equivalent is:
|
|
|
|
```python
|
|
%matplotlib widget
|
|
import sys; sys.path.insert(0, "/sf/bernina/code/gac-bernina/eco/")
|
|
from eco import bernina
|
|
from eco.bernina import *
|
|
```
|
|
|
|
<!-- TODO(eco docs): confirm whether a beamline-specific launcher script
|
|
(e.g. one opening JupyterLab directly in the default environment) still
|
|
exists / is the recommended entry point alongside `eco jupyterlab`, and
|
|
document it here if so. -->
|
|
|
|
`bernina` is the instrument object (a lazy {doc}`Namespace <concepts>` — its
|
|
components initialise only when you touch them). From there, `bernina.status()`,
|
|
`bernina.get_tree(level=-1)` and `bernina.namespace.all_names` are good first
|
|
commands.
|
|
|
|
## With conda
|
|
|
|
eco is published on [anaconda.org](https://anaconda.org/paulscherrerinstitute/eco):
|
|
|
|
```bash
|
|
conda install -c paulscherrerinstitute eco
|
|
```
|
|
|
|
:::{note}
|
|
This packaging is currently being reworked and has not yet been re-verified
|
|
end to end. Until it has, prefer *From source* below.
|
|
:::
|
|
|
|
## From source
|
|
|
|
For development, install eco in editable mode from a checkout:
|
|
|
|
```bash
|
|
git clone https://github.com/paulscherrerinstitute/eco.git
|
|
cd eco
|
|
pip install -e .
|
|
```
|
|
|
|
<!-- TODO(eco docs): PSI staff developing on-site normally check out from the
|
|
internal Gitea (git@gitea.psi.ch:Bernina/eco.git) instead of the GitHub
|
|
mirror above; confirm the mirror's sync policy and, if it can lag, add an
|
|
explicit internal-clone instruction here. -->
|
|
|
|
On a beamline machine, install into the existing conda environment without
|
|
letting pip touch its (conda-managed) dependencies:
|
|
|
|
```bash
|
|
pip install -e . --no-deps
|
|
```
|
|
|
|
eco's core dependencies (numpy, scipy, EPICS, …) install normally with
|
|
`pip install -e .`; a further stack of hardware, beam-synchronous and PSI-only
|
|
libraries (`pyepics`, `bsread`, the PSI `datahub` package, `cam_server`, …) is
|
|
grouped into optional extras (`eco[gui]`, `eco[sheets]`, `eco[hardware]`,
|
|
`eco[lab]`, `eco[voila]`) and, for the PSI-internal/git-only packages,
|
|
`eco[psi]`. Several of these are only reachable inside the PSI network or a
|
|
PSI conda channel, so a full installation is generally done on a beamline
|
|
machine rather than a laptop.
|
|
|
|
----
|
|
|
|
## Development
|
|
|
|
The sections above are for *using* eco. The following is only relevant if you
|
|
are working on eco itself.
|
|
|
|
### Building this documentation
|
|
|
|
The documentation is built with [Sphinx](https://www.sphinx-doc.org):
|
|
|
|
```bash
|
|
pip install -r docs/requirements.txt
|
|
sphinx-build -b html docs docs/_build/html
|
|
```
|
|
|
|
Open `docs/_build/html/index.html` in a browser. The same configuration is used
|
|
by [Read the Docs](https://readthedocs.org) via the `.readthedocs.yaml` file in
|
|
the repository root.
|