From c4b83f53f2c6deb8964c3fd31443df6126ce9c37 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Wed, 9 Sep 2026 09:05:05 +0200 Subject: [PATCH 1/2] docs: document conda-forge installation --- README.md | 53 ++-------------------- docs/source/installation_and_structure.rst | 16 ++++++- 2 files changed, 19 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 69e076d8..5c164175 100644 --- a/README.md +++ b/README.md @@ -12,61 +12,16 @@ for guidance on using the code. Installation ------------ -Cherab is a large code framework consisting of a core package and feature -packages. Users will generally install the core package and the specific -feature packages they need for their work. For example, users working on the -JET tokamak will require the `cherab-core` package, and the `cherab-jet` -package. +Cherab can be installed with pip from PyPI or with conda from conda-forge: -Unless developing new code for a cherab package, most users should clone the -master branch. When developing new features for cherab, the development branch -should be used as the base. - -All cherab packages are standard python packages and basic installation is -achieved with: - -``` +```sh pip install cherab ``` -This will compile the Cherab cython extensions and install the package. If you -don't have administrator access to install the package, add the `--user` flag -to the above line to install the package under your own user account. -Alternatively, consider creating a [virtual environment](https://docs.python.org/3/tutorial/venv.html) -and installing `cherab` in the environment. - -When developing cherab it is usually preferred that the packages be installed -in "editable" mode. Clone this repository and change directory to the root of -the repository, then run: - -``` -pip install -e . +```sh +conda install --channel conda-forge cherab ``` -This will cause the original installation folder to be added to the site-package -path. Modifications to the code will therefore be visible to python next time -the code is imported. A virtual environment or the ``--user`` flag should be -used if you do not have administrative permission for your python installation. -If you make any changes to Cython files you will need to run `./dev/build.sh` to -rebuild the relevant files. - -As all the Cherab packages are dependent on the ``cherab-core`` package, this -package must be installed first. Note that other packages may have their own -inter-dependencies, see the specific package documentation for more information. - -Cherab is organised as a namespace package, where each of the submodules is -installed in the same location as the core package. Any submodules using Cython -with a build-time dependency on Cherab need to use a Cython version newer than -3.0a5, due to a [bug](https://github.com/cython/cython/issues/2918) in how -earlier versions of Cython handle namespaces. - -By default, pip will install from wheel archives on PyPI. If a binary wheel is not -available for your version of Python, or if you are installing in editable mode -for development, the package will be compiled locally on your machine. Compilation -is done in parallel by default, using all available processors, but can be -overridden by setting the environment variable `CHERAB_NCPU` to the number of -processors to use. - Governance ---------- diff --git a/docs/source/installation_and_structure.rst b/docs/source/installation_and_structure.rst index e9c051bf..94838d8e 100644 --- a/docs/source/installation_and_structure.rst +++ b/docs/source/installation_and_structure.rst @@ -61,7 +61,7 @@ Installation Users will generally just install the core package and the specific feature packages they need for their work. For example, users working on the JET tokamak will require the `cherab `_ package and the `cherab-jet `_ -package. The core ``cherab`` package is available through pip. The additional fusion specific +package. The core ``cherab`` package is available through pip and conda. The additional fusion specific packages, offering extra functionality, should be cloned from their respective repositories. @@ -89,6 +89,20 @@ default, using all available processors, but can be overridden by setting the en ``CHERAB_NCPU`` to the number of processors to use. +Installing through conda +^^^^^^^^^^^^^^^^^^^^^^^^ + +Pre-built Cherab packages are available from the +`conda-forge channel `_ for Linux and macOS. +To install Cherab with conda, run:: + + conda install --channel conda-forge cherab + +This installs Cherab and its dependencies, including Raysect, without requiring +a local compiler. The OpenADAS module is included, but its atomic data files must +be downloaded separately as described in `Configuring Atomic Data`_ below. + + Installing from source ^^^^^^^^^^^^^^^^^^^^^^ From a92e6afacfe2bd7a63d15837f1a08fe0b3565f2a Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Wed, 9 Sep 2026 09:27:44 +0200 Subject: [PATCH 2/2] docs: preserve README content and add conda command --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5c164175..3065b391 100644 --- a/README.md +++ b/README.md @@ -12,16 +12,67 @@ for guidance on using the code. Installation ------------ -Cherab can be installed with pip from PyPI or with conda from conda-forge: +Cherab is a large code framework consisting of a core package and feature +packages. Users will generally install the core package and the specific +feature packages they need for their work. For example, users working on the +JET tokamak will require the `cherab-core` package, and the `cherab-jet` +package. -```sh +Unless developing new code for a cherab package, most users should clone the +master branch. When developing new features for cherab, the development branch +should be used as the base. + +All cherab packages are standard python packages and basic installation is +achieved with: + +``` pip install cherab ``` +This will compile the Cherab cython extensions and install the package. If you +don't have administrator access to install the package, add the `--user` flag +to the above line to install the package under your own user account. +Alternatively, consider creating a [virtual environment](https://docs.python.org/3/tutorial/venv.html) +and installing `cherab` in the environment. + +Cherab can also be installed with conda from the conda-forge channel: + ```sh conda install --channel conda-forge cherab ``` +When developing cherab it is usually preferred that the packages be installed +in "editable" mode. Clone this repository and change directory to the root of +the repository, then run: + +``` +pip install -e . +``` + +This will cause the original installation folder to be added to the site-package +path. Modifications to the code will therefore be visible to python next time +the code is imported. A virtual environment or the ``--user`` flag should be +used if you do not have administrative permission for your python installation. +If you make any changes to Cython files you will need to run `./dev/build.sh` to +rebuild the relevant files. + +As all the Cherab packages are dependent on the ``cherab-core`` package, this +package must be installed first. Note that other packages may have their own +inter-dependencies, see the specific package documentation for more information. + +Cherab is organised as a namespace package, where each of the submodules is +installed in the same location as the core package. Any submodules using Cython +with a build-time dependency on Cherab need to use a Cython version newer than +3.0a5, due to a [bug](https://github.com/cython/cython/issues/2918) in how +earlier versions of Cython handle namespaces. + +By default, pip will install from wheel archives on PyPI. If a binary wheel is not +available for your version of Python, or if you are installing in editable mode +for development, the package will be compiled locally on your machine. Compilation +is done in parallel by default, using all available processors, but can be +overridden by setting the environment variable `CHERAB_NCPU` to the number of +processors to use. + Governance ----------