diff --git a/.ci_support/environment-mpich.yml b/.ci_support/environment-mpich.yml index 7b779f40..f1967d4d 100644 --- a/.ci_support/environment-mpich.yml +++ b/.ci_support/environment-mpich.yml @@ -5,11 +5,11 @@ dependencies: - numpy - mpich - cloudpickle =3.0.0 -- conda_subprocess =0.0.4 +- conda_subprocess =0.0.5 - mpi4py =4.0.0 - pyzmq =26.2.0 - h5py =3.11.0 - matplotlib =3.9.2 - networkx =3.3 -- pygraphviz =1.13 +- pygraphviz =1.14 - ipython =8.27.0 diff --git a/.ci_support/environment-openmpi.yml b/.ci_support/environment-openmpi.yml index 9c56a991..eb356641 100644 --- a/.ci_support/environment-openmpi.yml +++ b/.ci_support/environment-openmpi.yml @@ -5,11 +5,11 @@ dependencies: - numpy - openmpi - cloudpickle =3.0.0 -- conda_subprocess =0.0.4 +- conda_subprocess =0.0.5 - mpi4py =4.0.0 - pyzmq =26.2.0 - h5py =3.11.0 - matplotlib =3.9.2 - networkx =3.3 -- pygraphviz =1.13 +- pygraphviz =1.14 - ipython =8.27.0 diff --git a/.ci_support/environment-win.yml b/.ci_support/environment-win.yml index d0350241..0953804d 100644 --- a/.ci_support/environment-win.yml +++ b/.ci_support/environment-win.yml @@ -5,11 +5,11 @@ dependencies: - numpy - msmpi - cloudpickle =3.0.0 -- conda_subprocess =0.0.4 +- conda_subprocess =0.0.5 - mpi4py =4.0.0 - pyzmq =26.2.0 - h5py =3.11.0 - matplotlib =3.9.2 - networkx =3.3 -- pygraphviz =1.13 +- pygraphviz =1.14 - ipython =8.27.0 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 56076c01..c5b2707c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.6.4 + rev: v0.6.8 hooks: - id: ruff name: ruff lint diff --git a/docs/_config.yml b/docs/_config.yml index 3f9eefc2..3399770c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,6 +1,5 @@ title: executorlib author: Jan Janssen -logo: images/pyiron-logo.png execute: execute_notebooks : off diff --git a/docs/_toc.yml b/docs/_toc.yml index bf2b2f63..541e17d6 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -4,4 +4,5 @@ chapters: - file: installation.md - file: examples.ipynb - file: development.md -- file: api.rst \ No newline at end of file +- file: trouble_shooting.md +- file: api.rst diff --git a/docs/trouble_shooting.md b/docs/trouble_shooting.md new file mode 100644 index 00000000..8d79e140 --- /dev/null +++ b/docs/trouble_shooting.md @@ -0,0 +1,103 @@ +# Trouble shooting + +## When `flux` fails: + +### Step-by-Step Guide to Create a Custom Jupyter Kernel for Flux + +#### Step 1: Create a New Kernel Specification + +1. Install [`flux-core`](https://anaconda.org/conda-forge/flux-core) in your Jupyter environment: + + ```bash + conda install -c conda-forge flux-core + ``` + +2. **Find the Jupyter Kernel Directory**: + + Open your terminal or command prompt and run: + + ```bash + jupyter --paths + ``` + + This command will display the paths where Jupyter looks for kernels. You'll usually find a directory named `kernels` under the `jupyter` data directory. You will create a new directory for the Flux kernel in the `kernels` directory. + +3. **Create the Kernel Directory**: + + Navigate to the kernels directory (e.g., `~/.local/share/jupyter/kernels` on Linux or macOS) and create a new directory called `flux`. + + ```bash + mkdir -p ~/.local/share/jupyter/kernels/flux + ``` + + If you're using Windows, the path will be different, such as `C:\Users\\AppData\Roaming\jupyter\kernels`. + +4. **Create the `kernel.json` File**: + + Inside the new `flux` directory, create a file named `kernel.json`: + + ```bash + nano ~/.local/share/jupyter/kernels/flux/kernel.json + ``` + + Paste the following content into the file: + + ```json + { + "argv": [ + "flux", + "start", + "/srv/conda/envs/notebook/bin/python", + "-m", + "ipykernel_launcher", + "-f", + "{connection_file}" + ], + "display_name": "Flux", + "language": "python", + "metadata": { + "debugger": true + } + } + ``` + + - **`argv`**: This array specifies the command to start the Jupyter kernel. It uses `flux start` to launch Python in the Flux environment. + - **`display_name`**: The name displayed in Jupyter when selecting the kernel. + - **`language`**: The programming language (`python`). + + **Note**: + + - Make sure to replace `"/srv/conda/envs/notebook/bin/python"` with the correct path to your Python executable. You can find this by running `which python` or `where python` in your terminal. + - If you installed `flux` in a specific environment, you have to write the absolute path to `flux` in the `argv` array. + +#### Step 2: Restart Jupyter Notebook + +1. **Restart the Jupyter Notebook Server**: + + Close the current Jupyter Notebook server and restart it: + + ```bash + jupyter notebook + ``` + + ```bash + jupyter lab + ``` + + Or simply restart your server. + +2. **Select the Flux Kernel**: + + When creating a new notebook or changing the kernel of an existing one, you should see an option for "Flux" in the list of available kernels. Select it to run your code with the Flux environment. + +#### Step 3: Run Your Code with `FluxExecutor` + +Now, your Jupyter environment is set up to use `flux-core`. You can run your code like this: + +```python +import flux.job + +# Use FluxExecutor within the Flux kernel +with flux.job.FluxExecutor() as flux_exe: + print("FluxExecutor is running within the Jupyter Notebook") +``` diff --git a/pyproject.toml b/pyproject.toml index afbc7b92..c834af44 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,13 +35,13 @@ Documentation = "https://executorlib.readthedocs.io" Repository = "https://github.com/pyiron/executorlib" [project.optional-dependencies] -conda = ["conda_subprocess==0.0.4"] +conda = ["conda_subprocess==0.0.5"] mpi = ["mpi4py==4.0.0"] hdf = [ "h5py==3.11.0", ] graph = [ - "pygraphviz==1.13", + "pygraphviz==1.14", "matplotlib==3.9.2", "networkx==3.3", "ipython==8.27.0",