Installation Guide¶

This work is licensed under a Creative Commons Attribution 4.0 International License.

This guide covers setting up the development environment for running fractal visualization applications locally.

Prerequisites¶

For React Applications¶

• Node.js (v16 or later)
• npm (v8 or later)
• Modern web browser with WebGL support

For Python Applications¶

• Python (v3.8 or later)
• pip or conda package manager
• Optional: CUDA-capable GPU for accelerated computation

React Application Setup¶

1. Clone the Repository¶

git clone https://github.com/tyson-swetnam/fractal-notebooks
cd fractal-notebooks/react

2. Install Dependencies¶

npm ci

3. Start Development Server¶

npm start

The application will be available at http://localhost:33000.

4. Build for Production¶

npm run build

Available Scripts¶

Python Environment Setup¶

Option 1: Using pip¶

pip install streamlit numpy scipy matplotlib plotly pillow imageio

The four tree-ring apps (app.py to app4.py) also need pandas, and app3.py needs shapely. The repository's root requirements.txt is the documentation toolchain, not the app stack.

Option 2: Using Conda with Mamba¶

1. Install Miniconda

   macOSLinuxWindows

   curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
   bash Miniconda3-latest-MacOSX-x86_64.sh
   

   curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
   bash Miniconda3-latest-Linux-x86_64.sh
   

   Download from Miniconda website and run the installer.

2. Install Mamba (faster solver)

   conda install mamba -n base -c conda-forge
   

3. Create Environment

   cd fractal-notebooks/docs/notebooks
   mamba env create -f streamlit-plotly.yaml
   

4. Activate Environment

   mamba activate streamlit-plotly
   

Running Streamlit Applications¶

After setting up the Python environment:

cd apps
streamlit run tree_roots_3d.py

Available Applications¶

The full catalogue of the twelve Streamlit apps, and of the matplotlib/PIL scripts (mandelbrot.py, julia.py, branching_tree.py, pythagoras_tree.py) that are run with python rather than streamlit, is on the Streamlit Apps page.

Jupyter Notebook Setup¶

Install Jupyter Kernel¶

mamba activate streamlit-plotly
mamba install -c conda-forge jupyterlab ipykernel
python -m ipykernel install --name streamlit-plotly --display-name "Python (streamlit-plotly)"

Launch JupyterLab¶

jupyter lab

Navigate to the docs/notebooks/ directory to access the example notebooks.

GPU Acceleration (Optional)¶

CUDA Setup for PyTorch¶

For GPU-accelerated computation with PyTorch:

Verify GPU Access¶

import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"Device count: {torch.cuda.device_count()}")
if torch.cuda.is_available():
    print(f"Device name: {torch.cuda.get_device_name(0)}")

Docker Setup¶

For containerized deployment:

# from the repository root (the Dockerfile copies apps/)
docker build -f docker/Dockerfile -t fractal-app .
docker run -p 8501:8501 fractal-app

Troubleshooting¶

Common Issues¶

Node.js version mismatch

nvm install 18
nvm use 18

Python package conflicts

mamba env remove -n streamlit-plotly
mamba env create -f streamlit-plotly.yaml

WebGL not available - Update graphics drivers - Try a different browser - Check browser WebGL support at get.webgl.org

Getting Help¶

• Open an issue on GitHub
• Check existing documentation in this guide