eco/docs/installation.md

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:

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:

[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:

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:

%matplotlib widget
import sys; sys.path.insert(0, "/sf/bernina/code/gac-bernina/eco/")
from eco import bernina
from eco.bernina import *

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:

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:

git clone https://github.com/paulscherrerinstitute/eco.git
cd eco
pip install -e .

On a beamline machine, install into the existing conda environment without letting pip touch its (conda-managed) dependencies:

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:

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 via the .readthedocs.yaml file in the repository root.