### Install Dependencies with uv

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Installs all optional dependencies for development using the `uv` package manager. Ensure `uv` is installed and then activate your environment.

```bash
uv sync --all-extras
```

--------------------------------

### Install Project with Poetry

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Installs the project dependencies, including all optional extras, using Poetry. Use `--extra test` or `--extra docs` for specific subsets.

```bash
poetry install --all-extras
```

--------------------------------

### Build and Setup Script for Molecular Nodes

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Use this command to display help for the build script. It manages package downloads and add-on zip file creation.

```bash
blender -b -P build.py -- -help
```

--------------------------------

### Full Build and Setup for Molecular Nodes

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

This command executes the complete build process for the Molecular Nodes add-on, including downloading packages and building the zip files. It's the primary command for initial setup.

```bash
blender -b -P build.py
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Install pre-commit hooks to ensure code is formatted correctly before committing. Activate your dev environment before running.

```bash
pre-commit install
```

--------------------------------

### Complete Workflow for Publication-Quality Render

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

A comprehensive example demonstrating the setup of a rendering canvas with Cycles, loading a protein structure, applying multiple styles (cartoon, spheres, sticks), highlighting specific residues, and rendering multiple views. Includes camera lens adjustment and background color configuration.

```python
import molecularnodes as mn
import numpy as np

# Setup rendering canvas
canvas = mn.Canvas(
    engine=mn.scene.Cycles(samples=64),
    resolution=(1920, 1080),
    transparent=False
)
cvas.background = (0.05, 0.05, 0.08, 1.0)
cvas.view_transform = "AgX"

# Load protein structure
mol = mn.Molecule.fetch("6LU7")  # SARS-CoV-2 main protease

# Add cartoon style for protein backbone
mol.add_style(
    mn.StyleCartoon(
        quality=4,
        peptide_arrows=True,
        peptide_thickness=0.6
    ),
    color="chain",
    material=mn.material.AmbientOcclusion()
)

# Highlight active site residues with spheres
active_site = mol.select.res_id([41, 145, 163, 164]).is_amino_acid()
mol.add_style(
    mn.StyleBallAndStick(sphere_radius=0.5, bond_radius=0.2),
    selection=active_site,
    color="common"
)

# Show ligand if present
mol.add_style(
    mn.StyleSticks(radius=0.25),
    selection=mol.select.is_ligand(),
    material=mn.material.Material.neon()
)

# Frame and render
canvas.frame_object(mol, viewpoint="front")
canvas.camera.lens = 100
canvas.snapshot("protease_render.png")

# Render multiple views
for view in ["front", "top", "left"]:
    canvas.frame_object(mol, viewpoint=view)
    canvas.snapshot(f"protease_{view}.png")

# Clean up
canvas.clear()
```

--------------------------------

### Build Add-on Zip Files with Build Script

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Run this command to build the .zip files for the Molecular Nodes add-on after packages have been downloaded. This is part of the setup process.

```bash
blender -b -P build.py -- -build-only
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Creates a new Conda environment named 'mn' with Python 3.11, activates it, and installs Poetry.

```bash
conda create -n mn python==3.11
conda activate mn
pip install poetry
```

--------------------------------

### Scene Setup and Rendering with Canvas

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Use the Canvas class to configure Blender scenes, control render settings, and generate images or animations. Supports Cycles and EEVEE rendering engines.

```python
import molecularnodes as mn

# Create a canvas with Cycles rendering at 800x800 resolution
canvas = mn.Canvas(
    engine=mn.scene.Cycles(samples=32),
    resolution=(800, 800),
    transparent=True
)

# Alternative: Use EEVEE for faster rendering
canvas = mn.Canvas(engine="EEVEE", resolution=(1280, 720))

# Configure scene properties
canvas.transparent = True
canvas.background = (0.1, 0.1, 0.1, 1.0)  # RGBA
canvas.fps = 24
canvas.frame_start = 1
canvas.frame_end = 100
canvas.view_transform = "AgX"  # Color management

# Render a single frame
canvas.snapshot("output.png")
canvas.snapshot("output.png", frame=50, file_format="PNG")

# Render animation
canvas.animation("output.mp4", frame_start=1, frame_end=100)

# Clear all molecular entities from scene
canvas.clear()

# Reset scene from template
canvas.scene_reset(template="Molecular Nodes")
```

--------------------------------

### Canvas - Scene Setup and Rendering

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

The Canvas class provides a high-level interface for configuring Blender scenes, controlling render settings, and generating images or animations of molecular structures.

```APIDOC
## Canvas Class

### Description
Configures the Blender scene environment, render engine settings, and handles output generation for snapshots and animations.

### Methods
- **snapshot(filename, frame, file_format)**: Renders a single frame to an image file.
- **animation(filename, frame_start, frame_end)**: Renders an animation sequence.
- **clear()**: Removes all molecular entities from the scene.
- **scene_reset(template)**: Resets the scene using a specified template.

### Request Example
```python
canvas = mn.Canvas(engine=mn.scene.Cycles(samples=32), resolution=(800, 800))
canvas.snapshot("output.png")
```
```

--------------------------------

### Build and Preview Documentation

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Build and preview the project documentation using Quarto. This process may take several minutes on the first run as it executes all code, including rendering 3D images. Subsequent builds are faster. Ensure your dev environment is active and navigate to the docs directory.

```bash
cd docs
python generate.py
quartodoc build
quartodoc interlinks
quarto preview
```

--------------------------------

### Configure Cycles and EEVEE Render Engines

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Shows how to configure the Cycles and EEVEE render engines for different quality and speed tradeoffs. Includes setting samples for Cycles and switching between engines.

```python
import molecularnodes as mn

# High-quality Cycles rendering
canvas = mn.Canvas(
    engine=mn.scene.Cycles(
        samples=128,           # Ray samples (higher = less noise)
        # Additional Cycles options configured via bpy
    ),
    resolution=(1920, 1080)
)

# Fast EEVEE rendering
canvas = mn.Canvas(
    engine=mn.scene.EEVEE(),
    resolution=(1920, 1080)
)

# Switch engines
canvas.engine = "CYCLES"
canvas.engine = "EEVEE"
canvas.engine = mn.scene.Cycles(samples=64)

# Render with current engine
mol = mn.Molecule.fetch("4ozs")
mol.add_style(mn.StyleCartoon())
canvas.frame_object(mol)
canvas.snapshot("render.png")
```

--------------------------------

### Batch Download Structures with Caching

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Demonstrates downloading multiple structure files using StructureDownloader with caching support. Shows downloading from PDB and AlphaFold, disabling cache, and batch downloading.

```python
import molecularnodes as mn
from molecularnodes.download import StructureDownloader

# Create downloader with custom cache
downloader = StructureDownloader(cache="/path/to/cache")

# Download structure files
path = downloader.download("1abc", format="cif")
path = downloader.download("1abc", format="bcif")
path = downloader.download("1abc", format="pdb")

# Download from AlphaFold
path = downloader.download("Q8W3K0", format="cif", database="alphafold")

# Disable caching (returns BytesIO/StringIO)
downloader = StructureDownloader(cache=None)
file_obj = downloader.download("1abc", format="cif")

# Batch download
pdb_codes = ["1abc", "2def", "3ghi"]
for code in pdb_codes:
    path = downloader.download(code, format="bcif")
    mol = mn.Molecule.load(path, name=code)
```

--------------------------------

### Accessing Blender Data and Operators via bpy

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Demonstrates the primary entry points for interacting with Blender's internal data structures and operator system.

```python
import bpy

bpy.data                        # Access all of the data blocks inside of Blender
bpy.data.objects                # access all of the objects in the scene by name

cube = bpy.data.objects['Cube'] # get the data block for an object in Blender
cube.data                       # the data associated with the cube, such as edges, vertices, faces
cube.data.attributes
cube.data.vertices

bpy.ops                         # all of the pre-defined operators inside of Blender

bpy.context                     # all of the global context values, i.e. different properties set in the UI
bpy.types                       # the different pre-defined types used through bpy
```

--------------------------------

### Camera Control for Molecular Objects

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Demonstrates various methods to control camera framing for molecular objects, including framing the entire object, specific viewpoints, and using entity bounding boxes. Also shows how to set camera properties like focal length.

```python
import molecularnodes as mn

canvas = mn.Canvas()
mol = mn.Molecule.fetch("4ozs")
mol.add_style(mn.StyleCartoon())

# Frame entire object in view
canvas.frame_object(mol)

# Frame with specific viewpoint
canvas.frame_object(mol, viewpoint="front")
canvas.frame_object(mol, viewpoint="back")
canvas.frame_object(mol, viewpoint="top")
canvas.frame_object(mol, viewpoint="bottom")
canvas.frame_object(mol, viewpoint="left")
canvas.frame_object(mol, viewpoint="right")

# Frame using entity's view (bounding box)
canvas.frame_view(mol)
canvas.frame_view(mol, viewpoint="top")

# For trajectories with selection-based views
import MDAnalysis as mda
u = mda.Universe("topology.pdb")
traj = mn.Trajectory(u)
traj.add_style(mn.StyleSpheres())

# Frame specific selection at specific frame
view = traj.get_view(selection="protein", frame=50)
canvas.frame_view(view)

# Camera properties
canvas.camera.lens = 85           # Focal length
canvas.camera.set_viewpoint("front")

canvas.snapshot()
```

--------------------------------

### Download Packages with Build Script

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Execute this command to download required Python packages for the Molecular Nodes add-on. Packages are sourced from uv.lock and saved as .whl files.

```bash
blender -b -P build.py -- -download-only
```

--------------------------------

### Activate uv Environment

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Activates the virtual environment created by `uv`. Alternatively, prefix commands with `uv run`.

```bash
source .venv/bin/activate
```

--------------------------------

### Visualize EM/Cryo-EM Density Maps

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Load density files and apply surface or wireframe styles with specific threshold and color settings.

```python
import molecularnodes as mn
from molecularnodes.entities.density import io as density_io

canvas = mn.Canvas()

# Load density map from .map file
density = density_io.load(
    file_path="/path/to/density.map",
    name="EMDensity",
    style="density_surface",  # or "density_wire"
    center=True,              # Center at origin
    invert=False,             # Invert density values
    overwrite=False           # Overwrite existing VDB cache
)

# Style classes for density
surface_style = mn.StyleDensitySurface(
    threshold=0.8,
    shade_smooth=True,
    hide_dust=0.0,
    color=(0.2, 0.51, 0.13, 1.0)
)

wire_style = mn.StyleDensityWire(
    threshold=0.8,
    hide_dust=20.0,
    wire_radius=1.0,
    wire_resolution=3,
    color=(0.1, 0.39, 0.1, 1.0)
)

canvas.frame_object(density)
canvas.snapshot()
```

--------------------------------

### Apply Molecular Styles

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Configure visual representations of molecules using Style classes and apply color schemes or materials.

```python
mol.add_style(mn.StyleSpheres(radius=0.8, geometry="Point"))
mol.add_style(mn.StyleCartoon(
    quality=3,
    peptide_cylinders=False,
    peptide_arrows=True,
    peptide_thickness=0.6,
    peptide_width=2.2,
    color_blur=True
))
mol.add_style(mn.StyleBallAndStick(
    sphere_radius=0.3,
    bond_radius=0.3,
    bond_split=True
))
mol.add_style(mn.StyleRibbon(
    quality=3,
    backbone_smoothing=0.5,
    backbone_radius=1.6,
    uv_map=True
))
mol.add_style(mn.StyleSurface(
    scale_radius=1.5,
    probe_size=1.0,
    relaxation_steps=10
))

# Color schemes: "common" (element), "chain", "residue", "pLDDT", custom attribute
mol.add_style(mn.StyleCartoon(), color="common")
mol.add_style(mn.StyleCartoon(), color="chain")
mol.add_style(mn.StyleCartoon(), color="pLDDT")  # For AlphaFold structures

# Apply material
mol.add_style(mn.StyleCartoon(), material=mn.material.AmbientOcclusion())

# Method chaining
mol.add_style(mn.StyleCartoon()).add_style(mn.StyleSpheres())

canvas.frame_object(mol)
canvas.snapshot()
```

--------------------------------

### Molecule.add_style - Apply Visual Styles

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Apply visual rendering styles to molecules with support for selections, colors, and materials.

```APIDOC
## Molecule.add_style

### Description
Applies a specific visual representation style to the molecular object.

### Parameters
- **style** (string) - Required - Style name: "spheres", "sticks", "cartoon", "ribbon", "ball_stick", "surface".

### Request Example
```python
mol.add_style("cartoon")
```
```

--------------------------------

### Apply Materials to Molecular Surfaces

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Use built-in material classes or factory methods to define the visual appearance of molecular structures.

```python
import molecularnodes as mn

canvas = mn.Canvas()
mol = mn.Molecule.fetch("4ozs")

# Built-in material classes
mol.add_style(mn.StyleCartoon(), material=mn.material.AmbientOcclusion())
mol.add_style(mn.StyleCartoon(), material=mn.material.Default())
mol.add_style(mn.StyleCartoon(), material=mn.material.FlatOutline())
mol.add_style(mn.StyleCartoon(), material=mn.material.Squishy())
mol.add_style(mn.StyleCartoon(), material=mn.material.TransparentOutline())

# Material factory methods
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.glass())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.gold())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.metallic())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.pearl())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.neon())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.velvet())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.waxy())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.toon())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.iridescent())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.holo())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.green_glow())
mol.add_style(mn.StyleSpheres(), material=mn.material.Material.subsurface())

# Create custom material with create_material()
custom_mat = mn.material.create_material(
    name="MyMaterial",
    base_color=(0.8, 0.2, 0.2, 1.0),
    metallic=0.5,
    roughness=0.3,
    emission_strength=0.0
)
mol.add_style(mn.StyleSpheres(), material=custom_mat)

canvas.frame_object(mol)
canvas.snapshot()
```

--------------------------------

### Add Styles and Render Trajectory

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Applies ribbon style with RMSF-based coloring to a trajectory and renders it. Requires pre-defined RMSF data.

```python
traj.store_named_attribute(colors_from_rmsf, "rmsf_colors")
traj.add_style(mn.StyleRibbon(), color="rmsf_colors")

canvas.frame_view(traj)
canvas.snapshot()
```

--------------------------------

### Visualize Molecular Dynamics Trajectories

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Load and animate MD trajectories using MDAnalysis integration.

```python
import molecularnodes as mn
import MDAnalysis as mda
from MDAnalysis.tests.datafiles import PSF, DCD

canvas = mn.Canvas()

# Create trajectory from MDAnalysis Universe
u = mda.Universe(PSF, DCD)
traj = mn.Trajectory(u, name="MyTrajectory")

# Or load directly from files
traj = mn.Trajectory.load(
    topology="/path/to/topology.psf",
    coordinates="/path/to/trajectory.dcd",
    name="MySimulation",
    style="spheres"
)

# Access trajectory properties
print(traj.universe)         # MDAnalysis Universe
print(traj.atoms)            # MDAnalysis AtomGroup
print(len(traj.universe.trajectory))  # Number of frames
print(traj.uframe)           # Current Universe frame

# Playback settings
traj.subframes = 2           # Interpolation steps between frames
traj.offset = 0              # Frame offset
traj.average = 0             # Frames to average for smoothing
traj.interpolate = True      # Enable position interpolation
traj.correct_periodic = True # Periodic boundary correction

# Add styles with MDAnalysis selection strings
traj.add_style(mn.StyleSpheres())
traj.add_style(mn.StyleSpheres(), selection="protein and name CA")
traj.add_style(mn.StyleCartoon(), selection="protein")
traj.add_style(mn.StyleSticks(), selection="resname LIG")

# Use AtomGroup for selection
protein = u.select_atoms("protein")
traj.add_style(mn.StyleRibbon(), selection=protein)

# Clear existing styles
traj.styles.clear()

# Store custom attributes
import numpy as np
custom_colors = np.random.rand(len(traj.atoms), 4)
traj.store_named_attribute(custom_colors, "my_colors")
traj.add_style(mn.StyleSpheres(), color="my_colors")

# Frame to specific view
canvas.frame_view(traj)
canvas.snapshot()

# Render animation
canvas.frame_start = 1
canvas.frame_end = len(u.trajectory)
canvas.animation("trajectory.mp4")
```

--------------------------------

### Run Pytest Tests

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Execute tests using pytest. Options include verbose output, targeting specific files, or pattern matching test names. Ensure your dev environment is active.

```bash
pytest -v # run with a more verbose output
```

```bash
pytest -v tests/test_load.py # run a single tests file
```

```bash
pytest -v -k centre # pattern match to 'centre' and only run tests with that in the name
```

--------------------------------

### Fix biotite CCD Issues with uv

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Runs a Python command using `uv` to resolve potential issues with `biotite` losing track of files, specifically related to CCD.

```bash
uv run python -m biotite.setup_ccd
```

--------------------------------

### Molecule.load - Load Local Files

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Load molecular structures from local files supporting PDB, CIF, BCIF, SDF, and MOL formats.

```APIDOC
## Molecule.load

### Description
Loads a molecular structure from a local file path into the Blender scene.

### Parameters
- **path** (string/Path) - Required - Path to the structure file.
- **name** (string) - Optional - Name for the molecular object.
- **remove_solvent** (bool) - Optional - Whether to remove water molecules.

### Request Example
```python
mol = mn.Molecule.load("/path/to/structure.pdb")
```
```

--------------------------------

### Load Local Molecular Structure Files

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Load molecular structures from local files supporting PDB, CIF, BCIF, SDF, and MOL formats. Provides access to underlying biotite AtomArray and supports centering and assembly retrieval.

```python
import molecularnodes as mn
from pathlib import Path

canvas = mn.Canvas()

# Load from file path
mol = mn.Molecule.load("/path/to/structure.pdb")
mol = mn.Molecule.load("/path/to/structure.cif", name="MyProtein")
mol = mn.Molecule.load(Path("/path/to/structure.bcif"))

# Load small molecule from SDF/MOL file
ligand = mn.Molecule.load("/path/to/ligand.sdf", remove_solvent=False)

# Access underlying biotite AtomArray
print(mol.array)           # biotite.structure.AtomArray
print(mol.array.coord)     # Atomic coordinates
print(mol.array.res_name)  # Residue names
print(mol.n_models)        # Number of conformations

# Center the molecule
mol.centre_molecule(method="centroid")  # or "mass"

# Get biological assemblies
assemblies = mol.assemblies()

# Render the structure
mol.add_style(mn.StyleSpheres())
canvas.frame_object(mol)
canvas.snapshot()
```

--------------------------------

### Select Atoms and Residues

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Create specific atom selections using chainable methods to apply styles to subsets of a molecule.

```python
import molecularnodes as mn

canvas = mn.Canvas()
mol = mn.Molecule.fetch("4ozs")

# Use selector through mol.select
sel = mol.select

# Chain selections (AND logic)
backbone_selection = sel.is_backbone()
protein_selection = sel.is_amino_acid()
chain_a = sel.chain_id("A")
specific_residues = sel.res_id([100, 101, 102])

# Selection methods available:
sel.atom_name("CA")                    # By atom name
sel.atom_name(["CA", "CB", "N"])       # Multiple atom names
sel.chain_id("A")                      # By chain
sel.chain_id(["A", "B"])               # Multiple chains
sel.res_id(100)                        # By residue number
sel.res_id([100, 101, 102])            # Multiple residues
sel.res_name("ALA")                    # By residue name
sel.res_name(["ALA", "GLY", "VAL"])    # Multiple residue names
sel.element(["C", "N", "O"])           # By element

# Structural selections
sel.is_amino_acid()
sel.is_canonical_amino_acid()
sel.is_nucleotide()
sel.is_canonical_nucleotide()
sel.is_backbone()
sel.is_peptide_backbone()
sel.is_phosphate_backbone()
sel.is_side_chain()
sel.is_peptide()
sel.is_polymer()
sel.is_carbohydrate()
sel.is_ligand()
sel.is_hetero()
sel.is_solvent()
sel.is_monoatomic_ion()

# Negation methods
sel.not_amino_acids()
sel.not_chain_id("A")
sel.not_res_name("HOH")
sel.not_solvent()

# Chain multiple selections
backbone_chain_a = mol.select.is_backbone().chain_id("A")

# Store selection as named attribute
mol.select.is_amino_acid().chain_id("A").store_selection("protein_chain_A")

# Apply style with selection
mol.add_style(mn.StyleCartoon(), selection=mol.select.is_backbone())
mol.add_style(mn.StyleSpheres(), selection=mol.select.is_ligand())

canvas.frame_object(mol)
canvas.snapshot()
```

--------------------------------

### Define a Basic Blender Operator and Add-on Registration

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Implements a custom operator, a UI menu function, and the necessary register/unregister lifecycle methods for a Blender add-on.

```python
import bpy

def my_function():
    print("hello world!")

class SimpleOperator(bpy.types.Operator):
    bl_idname = "wm.simple_operator"
    bl_label = "Simple Operator"

    def execute(self, context):
        #code to be executed by the operator goes in the `execute()` function
        my_function()

        # operators inside of Blender return `{'FINISHED'}` to signal they have completed
        # correctly and Blender can return control of the program back to the user.
        # This is why they are useful for UI operations, but less useful for scripting
        # other potential returns are 'CANCELLED', 'RUNNING_MODAL', 'PASS_THROUGH'
        return {'FINISHED'}

# define a menu that will appear inside of the Blender's UI
# the layout function `layout.operator()` will take a string name of the operator,
# and create a button in the UI which will execute the operator when the buttons is pressed
def menu_func(self, context):
    # you can input either the string for the operator name, or take that
    # name from the class itself
    self.layout.operator(SimpleOperator.bl_idname)
    self.layout.operator("wm.simple_operator")


# The `register()` and `unregister()` functions are run whenever Blender loads the
# addon. This occurs the first time the add-on is installed and enabled, and then whenever
# Blender is started while the add-on is enabled. For Blender to be aware of the operator's
# existence, it has to be registered (and unregistered when uninstalled). The same has to
# happen for the UI components
def register():
    bpy.utils.register_class(SimpleOperator)
    bpy.types.VIEW3D_MT_mesh.append(menu_func)

def unregister():
    bpy.utils.unregister_class(SimpleOperator)
    bpy.types.VIEW3D_MT_mesh.remove(menu_func)
```

--------------------------------

### Apply Visual Styles to Molecules

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Apply various visual rendering styles to molecules, including spheres, sticks, cartoon, ribbon, ball-and-stick, and surface representations. Styles can be added using string names.

```python
import molecularnodes as mn

canvas = mn.Canvas()
mol = mn.Molecule.fetch("4ozs")

# Add styles using string names
mol.add_style("spheres")
mol.add_style("sticks")
mol.add_style("cartoon")
mol.add_style("ribbon")
mol.add_style("ball_stick")
mol.add_style("surface")

```

--------------------------------

### Load molecular structures via Python

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CHANGELOG.md

Use these functions to import structures from the RCSB PDB database or from local files within the Blender Python console.

```python
import molecularnodes as mn

# to fetch structures from the protein data bank
struc_list = ['4ozs', '1xi4', '6n2y']
for pdb in struc_list:
    mn.load.molecule_rcsb(pdb, starting_style = 1)

# to open a local structure file
mn.load.molecule_local('file_path_here.pdb', 'SomeMoleculeName', starting_style = 2)
```

--------------------------------

### Store and Use Custom Named Attributes

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Attach custom per-atom data to molecules for coloring or selection, including integration with NumPy and Matplotlib.

```python
import molecularnodes as mn
import numpy as np
import matplotlib.cm as cm

canvas = mn.Canvas()
mol = mn.Molecule.fetch("4ozs")

# Store custom color array (RGBA per atom)
n_atoms = len(mol.array)
colors = np.random.rand(n_atoms, 4)  # Random colors
mol.store_named_attribute(colors, "random_colors")

# Use with colormaps
viridis = cm.get_cmap('viridis')
values = np.random.rand(n_atoms)
colors = viridis(values)
mol.store_named_attribute(colors, "viridis_colors")

# Store boolean selection attribute
is_large = mol.array.res_id > 50
mol.store_named_attribute(is_large, "large_residues")

# Use custom attributes
mol.add_style(mn.StyleSpheres(), color="random_colors")
mol.add_style(mn.StyleCartoon(), selection="large_residues")

# List available attributes
print(mol.list_attributes())

# Read attribute values back
attr_data = mol.named_attribute("random_colors")

# For trajectories
import MDAnalysis as mda
u = mda.Universe("topology.pdb", "trajectory.xtc")
traj = mn.Trajectory(u)

# Compute RMSF and store as color
from MDAnalysis.analysis import rms
ca = u.select_atoms("name CA")
rmsf = rms.RMSF(ca).run()

# Map RMSF to all atoms (broadcast from CA to full atom)

```

--------------------------------

### Molecular Data Flow Diagram

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Illustrates the data flow for molecular structures within Blender, indicating responsibilities of MDAnalysis (MDA), Blender's Python module (bpy), and Geometry Nodes (GN).

```mermaid
flowchart LR
A{Data File} -->|MDA|B
B(MDA.Universe) -->|bpy|C
B -->|MDA|B
C[Blender Object] -->|GN|D
C -->|GN|C
D -->|GN|C
D[Styled Molecule] --->|GN|D
```

--------------------------------

### Manage Dynamic Trajectory Selections

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Create and apply atom selections that update across trajectory frames using MDAnalysis integration.

```python
import molecularnodes as mn
import MDAnalysis as mda

canvas = mn.Canvas()
u = mda.Universe("topology.pdb", "trajectory.xtc")
traj = mn.Trajectory(u)

# Create selection from MDAnalysis selection string
sel = traj.selections.from_string("protein and name CA")

# Create selection from AtomGroup
protein = u.select_atoms("protein")
sel = traj.selections.from_atomgroup(protein)

# Apply style to selection
traj.add_style(mn.StyleSpheres(), selection="protein")
traj.add_style(mn.StyleCartoon(), selection="backbone")

# Complex selection examples
traj.add_style(mn.StyleSpheres(), selection="resname LYS and name NZ")
traj.add_style(mn.StyleSticks(), selection="around 5.0 resname LIG")

canvas.frame_view(traj)
canvas.snapshot()
```

--------------------------------

### Register Molecular Nodes Add-on Programmatically

Source: https://github.com/bradyajohnston/molecularnodes/blob/main/CONTRIBUTING.md

Manually triggers the registration of the Molecular Nodes add-on when scripting outside of the Blender GUI.

```python
import molecularnodes as mn
mn.register()
# other code here
```

--------------------------------

### Molecule.fetch - Download from PDB/AlphaFold

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Fetch molecular structures directly from the RCSB Protein Data Bank or AlphaFold Database with automatic caching.

```APIDOC
## Molecule.fetch

### Description
Downloads molecular structures from remote databases like RCSB or AlphaFold.

### Parameters
- **code** (string) - Required - The PDB ID or UniProt ID.
- **format** (string) - Optional - File format (.cif, .bcif, .pdb).
- **centre** (string) - Optional - Centering method ("centroid", "mass").
- **remove_solvent** (bool) - Optional - Whether to remove water molecules.
- **database** (string) - Optional - Source database ("rcsb", "alphafold").

### Request Example
```python
mol = mn.Molecule.fetch("4ozs", format=".bcif", database="rcsb")
```
```

--------------------------------

### Fetch Molecular Structures from PDB/AlphaFold

Source: https://context7.com/bradyajohnston/molecularnodes/llms.txt

Download molecular structures directly from the RCSB Protein Data Bank or AlphaFold Database with automatic caching. Supports various formats and centering options.

```python
import molecularnodes as mn

canvas = mn.Canvas()

# Fetch from RCSB PDB (default)
mol = mn.Molecule.fetch("4ozs")
mol = mn.Molecule.fetch("4ozs", format=".bcif")  # Binary CIF format
mol = mn.Molecule.fetch("4ozs", format=".pdb")   # Legacy PDB format

# Fetch from AlphaFold Database using UniProt ID
mol = mn.Molecule.fetch("Q8W3K0", database="alphafold")

# Options
mol = mn.Molecule.fetch(
    code="4ozs",
    format=".bcif",           # File format: .cif, .bcif, .pdb
    centre="centroid",        # Center molecule: "centroid", "mass", or None
    remove_solvent=True,      # Remove water molecules
    cache="/path/to/cache",   # Cache directory (default: ~/MolecularNodesCache)
    database="rcsb"           # Database: "rcsb", "pdb", "wwpdb", "alphafold"
)

# Add a style and render
mol.add_style(mn.StyleCartoon())
canvas.frame_object(mol)
canvas.snapshot("protein.png")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.