nano-crucible 2.0.1

Python Client for Crucible - National Archive for NSRC Observations

nano-crucible : National Archive for NSRC Observations

A Python client library and CLI tool for Crucible - the Molecular Foundry's data lakehouse for scientific research. Crucible stores experimental and synthetic data from DOE Nanoscale Science Research Centers (NSRCs), along with comprehensive metadata about samples, projects, instruments, and users.

🔬 What is Crucible?

Crucible is the centralized data infrastructure for the Molecular Foundry and other DOE Nanoscale Science Research Centers, providing:

• Unified data storage for experimental and synthetic data
• Rich metadata capture to associate with datasets
• Sample provenance tracking with parent-child relationships

✨ Features

🐍 Python API

• Dataset Management: Create, query, update, and download datasets
• Sample Tracking: Manage samples with hierarchical relationships and provenance
• Metadata: Store and retrieve scientific metadata and experimental parameters
• Linking: Connect datasets, samples, and create relationships programmatically

🖥️ Command-Line Interface

• crucible config: One-time setup and configuration management
• crucible dataset: Create, list, update, and manage datasets
• crucible sample: Create, list, and manage samples with relationships
• crucible project: Manage projects and users (admin)
• crucible open: Open resources in the Crucible Web Explorer with one command

📦 Installation

From PyPI (Recommended)

pip install nano-crucible

From GitHub (Latest Development)

pip install git+https://github.com/MolecularFoundryCrucible/nano-crucible

With Optional Dependencies

# Install with parser support (includes ASE for LAMMPS and MatEnsemble parsers)
pip install nano-crucible[parsers]

# Install everything
pip install nano-crucible[all]

# For development
pip install nano-crucible[dev]

For Development

git clone https://github.com/MolecularFoundryCrucible/nano-crucible.git
cd nano-crucible
pip install -e ".[dev]"

🚀 Quick Start

Configuration

First, configure your API credentials:

crucible config init

Get your API key at: https://crucible.lbl.gov/api/v1/user_apikey

Alternative (without terminal access): Initialize the client directly with your credentials:

from crucible import CrucibleClient
client = CrucibleClient(
    api_url="https://crucible.lbl.gov/api/v1",
    api_key="your-api-key-here"
)

Python API

from crucible import CrucibleClient
from crucible.models import BaseDataset

# Initialize client
client = CrucibleClient()

# Create a dataset
dataset = BaseDataset(
    dataset_name="My Experiment",
    measurement="XRD",
    project_id="my-project",
    public=False
)

result = client.datasets.create(
    dataset=dataset,
    scientific_metadata={"temperature_C": 300},
    keywords=["experiment", "test"]
)

print(f"Dataset created: {result['dsid']}")

📓 For complete examples, see the tutorial notebooks:

• Main Tutorial - Creating datasets, samples, linking, and downloading
• Project Management - Managing projects and users (admin)

Command-Line Interface

# Configure API credentials
crucible config init

# Create a dataset with files
crucible dataset create -i data.csv -n "My Dataset" -m "XRD" -pid my-project

# List datasets in a project
crucible dataset list -pid my-project

# Get dataset details
crucible dataset get DATASET_ID

# Create a sample
crucible sample create -n "Sample A" -pid my-project

# Link sample to dataset
crucible sample add-to-dataset SAMPLE_ID DATASET_ID

# Open a resource in your browser
crucible open DATASET_ID

📖 For complete CLI documentation, see cli/README.md

📖 Documentation

• Tutorial Notebooks: See examples/ - Comprehensive Jupyter notebooks with runnable examples
  • Main Tutorial - Datasets, samples, linking, downloading
  • Project Management - Projects and users (admin)
• CLI Documentation: See cli/README.md - Complete command-line reference
• Parser Documentation: See parsers/README.md - Custom data format parsers

🤝 Contributing

We welcome contributions! Areas where you can help:

• New parsers for additional data formats
• Bug reports and feature requests
• Documentation improvements
• Example notebooks and tutorials

📄 License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

🔗 Links

• Crucible API: https://crucible.lbl.gov/api/v1
• Crucible Web Interface: https://crucible-graph-explorer-776258882599.us-central1.run.app

💬 Support

For issues, questions, or feature requests:

• Discord Server: Join our Discord
• GitHub Issues: https://github.com/MolecularFoundryCrucible/nano-crucible/issues
• Email: [e-mail], [e-mail], [e-mail]

---

nano-crucible is developed and maintained by the Data Group at the Molecular Foundry at Lawrence Berkeley National Laboratory.