Question 1

What is MatCraft?

Accepted Answer

MatCraft is an AI-powered materials discovery and optimization platform designed to accelerate the development of advanced materials. It provides a unified workflow for defining material compositions, running surrogate-model-driven optimization, and exploring multi-objective trade-offs -- all without requiring deep expertise in machine learning or numerical optimization.

## Key Features

- **Surrogate Models**: MatCraft trains lightweight MLP (multi-layer perceptron) neural networks on your experimental or simulation data. These surrogates approximate expensive physics calculations in milliseconds, enabling rapid exploration of vast composition spaces.
- **CMA-ES Optimization**: The platform uses Covariance Matrix Adaptation Evolution Strategy (CMA-ES) to intelligently search the material parameter space. CMA-ES is a derivative-free optimizer well-suited for noisy, non-convex objective landscapes common in materials science.
- **Active Learning**: Rather than requiring thousands of data points up front, MatCraft uses acquisition functions (Expected Improvement, Upper Confidence Bound, etc.) to suggest the most informative experiments to run next, drastically reducing the number of costly evaluations needed.
- **Pareto Multi-Objective Optimization**: Real materials must balance competing properties -- for example, maximizing ionic conductivity while minimizing cost. MatCraft computes and visualizes Pareto fronts so you can make informed trade-off decisions.
- **16 Material Domains**: Out of the box, MatCraft ships with validated domain plugins for water membranes, lithium-ion batteries, perovskite solar cells, thermoelectrics, catalysts, polymer composites, and more.

MatCraft is available as a self-hosted platform with a FastAPI backend, a Next.js frontend dashboard, a Python SDK for programmatic access, and a CLI for scripting and CI/CD integration.

Question 2

How does MatCraft work?

Accepted Answer

MatCraft follows a structured pipeline to go from raw material data to optimized compositions. Here is the end-to-end workflow:

## 1. Define Your Material

You start by creating a **Material** definition -- either through the web UI, a YAML configuration file, or the Python SDK. A material definition specifies:

- **Components**: The elements or constituents that make up your material (e.g., polymer type, filler concentration, solvent ratio).
- **Parameters**: Continuous or discrete variables with bounds that define the search space.
- **Objectives**: The properties you want to optimize (e.g., maximize tensile strength, minimize permeability).
- **Constraints**: Hard limits that valid compositions must satisfy (e.g., component fractions must sum to 1.0).

## 2. Seed with Data

Import initial experimental data -- as few as 10-20 data points -- via CSV, JSON, or direct API calls. MatCraft uses this seed data to train an initial surrogate model.

## 3. Run a Campaign

A **Campaign** orchestrates the optimization loop. In each iteration, the surrogate model proposes candidate compositions, an acquisition function ranks them, and the top candidates are either evaluated by a physics model or flagged for experimental validation.

## 4. Iterate with Active Learning

The active learning loop automatically retrains the surrogate as new data arrives, refining its predictions and focusing the search on the most promising regions of the design space. Most campaigns converge in 5-15 iterations.

## 5. Analyze Results

The dashboard provides interactive Pareto plots, convergence charts, and exportable reports. You can compare campaigns, drill into individual candidates, and export optimized compositions for lab validation.

Question 3

Who is MatCraft for?

Accepted Answer

MatCraft is built for anyone involved in materials development who wants to reduce the time and cost of discovering optimal compositions. The platform is designed to be accessible to domain experts who may not have a background in machine learning.

## Primary Users

- **Materials Scientists & Engineers**: Researchers working on formulation optimization in academia or industry. MatCraft handles the ML and optimization so you can focus on domain expertise and experimental validation.
- **R&D Teams**: Product development groups that need to systematically explore material design spaces. MatCraft's campaign system supports collaborative workflows where multiple team members contribute data and review results.
- **Computational Chemists & Physicists**: Practitioners who run DFT, molecular dynamics, or other simulations. MatCraft can wrap your simulation codes as evaluation backends, then use surrogates to minimize the number of expensive runs needed.
- **Data Scientists in Materials**: ML practitioners who want a structured framework for Bayesian-style optimization rather than building custom pipelines from scratch.

## Use Cases

- Formulating water purification membranes with optimal flux-rejection trade-offs
- Designing battery electrolyte compositions for maximum ionic conductivity
- Optimizing perovskite solar cell absorber layers for efficiency and stability
- Discovering polymer blends that balance mechanical strength and processability
- Screening catalyst compositions for selectivity and activity

## Skill Level

No machine learning expertise is required for basic usage. The YAML-based configuration and guided UI walk you through setting up a campaign. Advanced users can customize surrogate architectures, write custom acquisition functions, or integrate external simulation codes via the Python SDK.

Question 4

Is MatCraft open source?

Accepted Answer

Yes, MatCraft's core optimization engine is open source under the Apache 2.0 license. This includes the Python library (`materia`), which contains the surrogate model framework, CMA-ES optimizer, active learning loop, Pareto analysis, and all 16 built-in domain plugins.

## What Is Open Source

- **Core Library** (`src/materia/`): All optimization, surrogate modeling, active learning, and domain plugin code.
- **CLI** (`materia` command): The command-line interface for running campaigns, importing data, and exporting results.
- **Domain Plugins**: All 16 material domain definitions, including physics models and parameter schemas.
- **Tests & Examples**: Full test suite and example configurations.

## What Is Source-Available / Commercial

- **Web Dashboard** (Next.js frontend): The browser-based UI with interactive visualizations, team collaboration features, and campaign management is available under a source-available license. It is free for individual and academic use; commercial teams require a paid license.
- **Managed Cloud Service**: The hosted version at matcraft.ai handles infrastructure, scaling, and backups for you. This is a paid service with a free tier.
- **Enterprise Features**: SSO/SAML integration, audit logging, priority support, and custom SLAs require an enterprise license.

## Contributing

We welcome contributions to the core library. See our contributing guide for details on submitting pull requests, running the test suite, and our code review process. All contributors must sign a Contributor License Agreement (CLA).

You can install the open-source core directly from PyPI:

```bash
pip install matcraft
```

Question 5

What programming languages does MatCraft support?

Accepted Answer

MatCraft is primarily a Python-based platform, but it provides multiple integration points so you can work in your preferred environment.

## Python (Primary)

The core library and SDK are written in Python 3.10+. This is the most fully-featured way to interact with MatCraft:

```python
from materia import Campaign, Material

material = Material.from_yaml("my_material.yaml")
campaign = Campaign(material=material, max_iterations=20)
campaign.run()
print(campaign.best_candidates(n=5))
```

## REST API (Language-Agnostic)

The FastAPI backend exposes a comprehensive REST API. Any language that can make HTTP requests can interact with MatCraft:

```bash
curl -X POST https://api.matcraft.ai/api/v1/campaigns \
  -H "Authorization: Bearer $MATCRAFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"material_id": "mem-001", "max_iterations": 20}'
```

## CLI

The `materia` CLI is useful for scripting, CI/CD pipelines, and quick interactions:

```bash
materia campaign run --config campaign.yaml --output results/
materia data import --file measurements.csv --material mem-001
```

## YAML Configuration

Most users define their materials and campaigns using YAML files, which require no programming at all. The YAML schema is fully documented and validated at load time.

## Jupyter Notebooks

MatCraft integrates well with Jupyter for interactive exploration. The SDK includes built-in visualization helpers that render Pareto plots and convergence charts directly in notebook cells.

## Future Language SDKs

We are evaluating TypeScript/JavaScript and Julia SDKs based on community demand. If you need a specific language binding, please open a feature request on GitHub.

Question 6

How does MatCraft handle data privacy?

Accepted Answer

MatCraft takes data privacy seriously. Materials research data is often proprietary, and we have designed the platform with multiple layers of protection.

## Self-Hosted Deployment

The recommended approach for sensitive data is self-hosting. When you run MatCraft on your own infrastructure, your data never leaves your network. The platform requires only a PostgreSQL database and optional Redis for task queuing -- no external telemetry or phone-home calls are made.

## Cloud Service Data Handling

If you use the managed cloud service at matcraft.ai:

- **Data Isolation**: Each organization's data is stored in a logically isolated database schema. There is no cross-tenant data access.
- **Encryption**: All data is encrypted at rest (AES-256) and in transit (TLS 1.3). Database backups are encrypted with customer-specific keys on Enterprise plans.
- **Retention**: You own your data. You can export all materials, campaigns, and results at any time via the API or dashboard. When you delete data, it is permanently removed from primary storage within 24 hours and from backups within 30 days.
- **Access Controls**: Role-based access control (RBAC) lets you define who can view, edit, or delete materials and campaigns within your organization.
- **Compliance**: The cloud service is hosted on AWS (us-east-1 and eu-west-1 regions). We are SOC 2 Type II compliant and can provide a Data Processing Agreement (DPA) for enterprise customers.

## No Training on Your Data

MatCraft does **not** use your material data to train any shared models. Your surrogate models are trained exclusively on your data and are never accessible to other users or used to improve the platform's general models.

## GDPR

For EU users, we comply with GDPR requirements including data portability, right to erasure, and data processing transparency. Contact privacy@matcraft.ai for details.

Question 7

How does MatCraft compare to other materials optimization tools?

Accepted Answer

MatCraft occupies a unique position in the materials informatics landscape by combining surrogate-driven optimization with domain-specific plugins in a single, integrated platform. Here is how it compares to common alternatives:

## vs. General Bayesian Optimization Libraries (BoTorch, Ax, Optuna)

These are excellent general-purpose optimizers, but they require significant setup work for materials problems. You need to implement your own parameter constraints, material-specific physics, and multi-objective handling. MatCraft provides all of this out of the box, with domain plugins that encode material-specific knowledge like composition constraints (fractions summing to 1.0) and physically meaningful parameter bounds.

## vs. Materials Databases (Materials Project, AFLOW, NOMAD)

These platforms focus on storing and querying existing materials data from DFT calculations. MatCraft is complementary -- you can import data from these databases as seed data for optimization campaigns. MatCraft's strength is in the *optimization* workflow: actively searching for new compositions rather than mining existing ones.

## vs. Custom ML Pipelines (scikit-learn, PyTorch)

Building your own surrogate + optimizer pipeline gives you maximum flexibility but requires substantial ML engineering effort. MatCraft handles the boilerplate -- model training, active learning scheduling, convergence detection, Pareto computation, and result visualization -- so your team can focus on domain science.

## vs. Commercial Platforms (Citrine, Uncountable)

MatCraft differentiates through its open-source core, self-hosting option, and transparent optimization algorithms. You are never locked into a vendor. The CMA-ES + MLP surrogate approach is well-understood and auditable, unlike black-box commercial solutions. MatCraft also offers a generous free tier for academics and small teams.

## When to Choose MatCraft

MatCraft is the best fit when you need multi-objective optimization with domain-aware constraints, want transparency into the optimization process, and prefer the flexibility of self-hosting or an open-source core.

Question 8

How can I get help and join the MatCraft community?

Accepted Answer

MatCraft has an active community of materials scientists, ML practitioners, and engineers. Here are all the ways to get help and connect:

## GitHub Discussions

The primary forum for questions, feature requests, and community interaction is [GitHub Discussions](https://github.com/matcraft/matcraft/discussions). This is the best place for:

- Usage questions and troubleshooting
- Feature requests and design discussions
- Sharing your optimization results and case studies
- Connecting with other users working on similar materials

## Bug Reports & Issues

If you encounter a bug, please open an issue on the [GitHub issue tracker](https://github.com/matcraft/matcraft/issues) with:

- Your MatCraft version (`materia --version`)
- A minimal reproducible example
- Relevant log output

## Documentation

Comprehensive documentation is available at [matcraft.ai/docs](https://matcraft.ai/docs), including:

- Getting started tutorials
- API reference (auto-generated from source)
- YAML configuration schema reference
- Domain plugin guides for each of the 16 supported materials

## Discord

Join our Discord server for real-time chat with the community and maintainers. We have channels organized by topic: `#general`, `#optimization-help`, `#domain-plugins`, `#show-and-tell`, and `#contributing`.

## Office Hours

The core team holds monthly virtual office hours (first Thursday of each month, 11am ET) where anyone can ask questions, demo their work, or discuss upcoming features. Recordings are posted to our YouTube channel.

## Enterprise Support

Paid plans include email support with guaranteed response times. Enterprise customers receive a dedicated Slack channel and access to the engineering team for custom integration assistance. See our pricing page for details.

Question 9

How do I create a MatCraft account?

Accepted Answer

Creating a MatCraft account takes less than two minutes. You have several options depending on whether you want to use the hosted cloud service or a self-hosted instance.

## Cloud Service (matcraft.io)

1. Visit [matcraft.ai/register](https://matcraft.ai/register).
2. Sign up with your email address or use OAuth via GitHub or Google.
3. Verify your email address by clicking the link sent to your inbox.
4. Choose your plan -- the **Free** tier includes 3 active campaigns and 1,000 evaluations per month, which is enough for most individual researchers.
5. You will be dropped into the dashboard with a guided onboarding tour.

## Self-Hosted Instance

If your organization runs a self-hosted MatCraft deployment, your administrator will provide the URL. Account creation depends on your organization's identity provider:

- **Local accounts**: Navigate to `https://your-instance.com/signup` and register with email/password.
- **SSO/SAML**: Click "Sign in with SSO" and authenticate through your organization's identity provider (Okta, Azure AD, etc.). Your account is created automatically on first login.

## API Token

After creating your account, generate an API token for CLI and SDK usage:

1. Go to **Settings > API Tokens** in the dashboard.
2. Click **Generate New Token**.
3. Copy the token and store it securely. Set it as an environment variable:

```bash
export MATCRAFT_TOKEN="mc_live_abc123..."
```

4. Verify connectivity:

```bash
materia auth whoami
```

Your token has the same permissions as your user account. For CI/CD pipelines, we recommend creating a dedicated service account with limited permissions.

Question 10

How do I create my first optimization campaign?

Accepted Answer

A campaign is the central unit of work in MatCraft. It ties together a material definition, seed data, a surrogate model, and an optimization strategy. Here is how to launch your first campaign in three steps.

## Step 1: Define Your Material

Create a YAML file describing your material's design space:

```yaml
# my_material.yaml
name: "polymer-membrane-v1"
domain: water_membrane
components:
  - name: polymer_concentration
    type: continuous
    bounds: [0.05, 0.40]
    unit: "wt%"
  - name: additive_loading
    type: continuous
    bounds: [0.0, 0.15]
    unit: "wt%"
  - name: crosslinker_ratio
    type: continuous
    bounds: [0.01, 0.10]
objectives:
  - name: water_flux
    direction: maximize
    unit: "L/m2/h"
  - name: salt_rejection
    direction: maximize
    unit: "%"
```

## Step 2: Import Seed Data

Provide initial measurements in CSV format:

```bash
materia data import --material my_material.yaml --file initial_data.csv
```

Your CSV should have columns matching each component name and objective name. A minimum of 10 data points is recommended; 20-30 points will produce a more reliable initial surrogate.

## Step 3: Launch the Campaign

```bash
materia campaign run \
  --config my_material.yaml \
  --max-iterations 15 \
  --batch-size 5 \
  --output results/
```

Or via the Python SDK:

```python
from materia import Campaign, Material

material = Material.from_yaml("my_material.yaml")
campaign = Campaign(
    material=material,
    max_iterations=15,
    batch_size=5,
)
campaign.run()
campaign.export("results/")
```

The campaign will train an initial surrogate, then iteratively propose candidates, evaluate them, and retrain. Progress is displayed in real-time on the dashboard or in terminal output. Typical campaigns with 3-5 parameters converge in 8-15 iterations.

Question 11

How do I import experimental data into MatCraft?

Accepted Answer

MatCraft supports multiple data import formats and methods. Your data forms the foundation for surrogate model training, so getting it right is important.

## Supported Formats

- **CSV** (recommended for tabular data)
- **JSON** (for structured or nested data)
- **Excel** (.xlsx) via the dashboard upload
- **Programmatic** via the Python SDK or REST API

## CSV Import

The simplest approach is a CSV file with columns for each component and objective:

```csv
polymer_concentration,additive_loading,crosslinker_ratio,water_flux,salt_rejection
0.15,0.05,0.03,45.2,92.1
0.20,0.08,0.05,38.7,95.3
0.25,0.10,0.04,32.1,97.0
```

Import via CLI:

```bash
materia data import --material mem-001 --file measurements.csv
```

## Python SDK

For programmatic import, especially when transforming data from other tools:

```python
import pandas as pd
from materia import Material
from materia.io import import_data

df = pd.read_csv("lab_results.csv")
# Rename columns if needed
df = df.rename(columns={"flux_lmh": "water_flux", "rejection_pct": "salt_rejection"})

material = Material.from_yaml("my_material.yaml")
import_data(material, df)
```

## Data Validation

MatCraft validates imported data against your material definition:

- **Bounds checking**: Values outside component bounds are flagged as warnings (not rejected, since real measurements can exceed expected ranges).
- **Missing values**: Rows with missing objective values are accepted but excluded from surrogate training. Missing component values cause the row to be rejected.
- **Duplicates**: Exact duplicate rows are detected and deduplicated with a warning.
- **Type coercion**: String values in numeric columns are automatically parsed where possible.

## Best Practices

- Start with at least 10 data points; 20-50 is ideal for 3-5 dimensional spaces.
- Include points spread across the design space, not just near known optima.
- If you have data from different experimental batches, include a batch column -- MatCraft can account for batch effects in surrogate training.

Question 12

How do I write a YAML configuration file for MatCraft?

Accepted Answer

YAML configuration files are the primary way to define materials and campaigns in MatCraft. The schema is designed to be readable and self-documenting.

## Material Definition

A material YAML defines the design space -- what can vary and what you want to optimize:

```yaml
name: "lithium-ion-cathode-v2"
domain: battery
description: "NMC cathode composition optimization"

components:
  - name: nickel_fraction
    type: continuous
    bounds: [0.3, 0.9]
    description: "Ni molar fraction in NMC"
  - name: manganese_fraction
    type: continuous
    bounds: [0.05, 0.4]
  - name: cobalt_fraction
    type: continuous
    bounds: [0.05, 0.3]
  - name: coating_thickness
    type: continuous
    bounds: [1.0, 20.0]
    unit: "nm"

constraints:
  - type: sum_equals
    components: [nickel_fraction, manganese_fraction, cobalt_fraction]
    value: 1.0
    tolerance: 0.001

objectives:
  - name: specific_capacity
    direction: maximize
    unit: "mAh/g"
  - name: cycle_retention
    direction: maximize
    unit: "%"
    description: "Capacity retention after 500 cycles"
  - name: material_cost
    direction: minimize
    unit: "$/kg"
```

## Campaign Configuration

Campaign settings can be included in the same file or a separate one:

```yaml
campaign:
  max_iterations: 20
  batch_size: 5
  surrogate:
    type: mlp
    hidden_layers: [64, 64]
    learning_rate: 0.001
    epochs: 200
  acquisition:
    type: expected_improvement
    exploration_weight: 0.1
  convergence:
    patience: 5
    min_improvement: 0.01
```

## Key Schema Rules

- **component types**: `continuous`, `discrete`, or `categorical`. Categorical components use `choices` instead of `bounds`.
- **objective directions**: `maximize` or `minimize`.
- **constraint types**: `sum_equals`, `sum_lte`, `ratio_between`, or `custom` (with a Python expression).
- All numeric bounds are inclusive.
- The `domain` field is optional but enables domain-specific physics models and validation.

## Validation

Validate your YAML before launching a campaign:

```bash
materia config validate my_material.yaml
```

This checks for schema errors, bound consistency, constraint feasibility, and warns about potential issues like very high-dimensional spaces or tight constraints.

Question 13

How do I run MatCraft locally?

Accepted Answer

MatCraft can run entirely on your local machine for development, testing, or air-gapped environments. There are two approaches: using just the Python core library, or running the full platform stack.

## Core Library Only (Simplest)

If you only need the optimization engine without the web dashboard:

```bash
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the core library
pip install matcraft

# Verify installation
materia --version
```

This gives you the CLI, Python SDK, all domain plugins, and the surrogate/optimizer stack. No database or additional services are required -- campaign state is stored in local SQLite by default.

## Full Platform Stack

To run the complete platform including the web dashboard, API server, and task queue:

### Prerequisites

- Python 3.10+
- Node.js 18+ and pnpm
- PostgreSQL 14+
- Redis 7+ (for Celery task queue)

### Setup

```bash
# Clone the repository
git clone https://github.com/matcraft/matcraft.git
cd matcraft

# Backend
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env  # Edit with your database credentials

# Run database migrations
materia db upgrade

# Start the API server
uvicorn materia.api:app --reload --port 8000

# In a separate terminal, start the Celery worker
celery -A materia.tasks worker --loglevel=info
```

```bash
# Frontend (in another terminal)
cd frontend
pnpm install
pnpm dev  # Starts on http://localhost:3000
```

### Environment Variables

Key variables in your `.env` file:

```
DATABASE_URL=postgresql://user:pass@localhost:5432/matcraft
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your-secret-key-here
MATCRAFT_ENV=development
```

The development server includes hot-reloading for both frontend and backend changes.

Question 14

How do I run MatCraft with Docker?

Accepted Answer

Docker is the recommended way to run the full MatCraft platform locally or in production. We provide pre-built images and a Docker Compose configuration that sets up all services.

## Quick Start with Docker Compose

```bash
# Clone the repository
git clone https://github.com/matcraft/matcraft.git
cd matcraft

# Copy and configure environment
cp .env.example .env
# Edit .env with your preferred settings (or use defaults for local dev)

# Start all services
docker compose up -d
```

This starts five containers:

| Service | Port | Description |
|---------|------|-------------|
| `matcraft-api` | 8000 | FastAPI backend |
| `matcraft-frontend` | 3000 | Next.js dashboard |
| `matcraft-worker` | -- | Celery task worker |
| `matcraft-db` | 5432 | PostgreSQL database |
| `matcraft-redis` | 6379 | Redis for task queue |

## Docker Compose File

The `docker-compose.yml` includes sensible defaults:

```yaml
services:
  api:
    build: ./backend
    ports: ["8000:8000"]
    env_file: .env
    depends_on: [db, redis]
  frontend:
    build: ./frontend
    ports: ["3000:3000"]
    environment:
      NEXT_PUBLIC_API_URL: http://api:8000
  worker:
    build: ./backend
    command: celery -A materia.tasks worker --loglevel=info --concurrency=4
    env_file: .env
    depends_on: [db, redis]
  db:
    image: postgres:16-alpine
    volumes: [pgdata:/var/lib/postgresql/data]
    environment:
      POSTGRES_DB: matcraft
      POSTGRES_USER: matcraft
      POSTGRES_PASSWORD: matcraft
  redis:
    image: redis:7-alpine
```

## GPU Support

For GPU-accelerated surrogate training, use the NVIDIA Container Toolkit:

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
```

## Production Considerations

- Mount a persistent volume for PostgreSQL data.
- Use a managed PostgreSQL service (RDS, Cloud SQL) for production workloads.
- Set strong passwords and a secure `SECRET_KEY` in your `.env` file.
- Configure a reverse proxy (nginx, Traefik) with TLS termination in front of the API and frontend.
- Scale workers horizontally by increasing the `--concurrency` flag or running multiple worker containers.

Question 15

How do I deploy MatCraft to the cloud?

Accepted Answer

MatCraft can be deployed to any cloud provider. We provide Terraform modules and Helm charts for the most common platforms.

## AWS (Recommended)

Our Terraform module sets up a production-ready deployment on AWS:

```bash
cd deploy/terraform/aws

# Configure variables
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your settings

terraform init
terraform plan
terraform apply
```

This provisions:

- **ECS Fargate** for the API, frontend, and worker containers (serverless, no EC2 instances to manage)
- **RDS PostgreSQL** with automated backups and Multi-AZ for high availability
- **ElastiCache Redis** for the task queue
- **ALB** with TLS termination using ACM certificates
- **CloudWatch** for logging and monitoring

Estimated cost: ~$150-300/month for a small team deployment.

## Google Cloud Platform

```bash
cd deploy/terraform/gcp
terraform init && terraform apply
```

Uses Cloud Run, Cloud SQL, and Memorystore.

## Kubernetes (Any Cloud)

For teams already running Kubernetes, we provide a Helm chart:

```bash
helm repo add matcraft https://matcraft.ai/materials/scatter
helm install matcraft matcraft/matcraft \
  --namespace matcraft \
  --set api.replicas=2 \
  --set worker.replicas=3 \
  --set postgresql.enabled=true \
  --set redis.enabled=true
```

## Key Configuration

Regardless of cloud provider, ensure you configure:

- **Database backups**: Enable automated daily backups with at least 7 days retention.
- **TLS**: All traffic should be encrypted. Use your cloud provider's certificate manager.
- **Secrets management**: Store database credentials and API keys in your cloud's secrets manager (AWS Secrets Manager, GCP Secret Manager, etc.), not in environment variables or config files.
- **Monitoring**: Set up alerts for API error rates, worker queue depth, and database connection pool usage.

## Scaling

MatCraft scales horizontally. The API servers are stateless and can be load-balanced. Workers can be scaled independently based on campaign workload. The database is typically the bottleneck -- use read replicas for dashboard queries if needed.

Question 16

How do I use the MatCraft Python SDK?

Accepted Answer

The Python SDK (`materia`) gives you full programmatic control over MatCraft. It is the most flexible way to interact with the platform and is ideal for integration into existing Python workflows, Jupyter notebooks, and CI/CD pipelines.

## Installation

```bash
pip install matcraft
```

For GPU-accelerated surrogate training:

```bash
pip install matcraft[gpu]
```

## Basic Workflow

```python
from materia import Campaign, Material
from materia.surrogate import MLPSurrogate
from materia.optimize import CMAESOptimizer
from materia.active_learning import ActiveLearningLoop

# 1. Define material from YAML or programmatically
material = Material(
    name="my-alloy",
    components=[
        {"name": "iron", "type": "continuous", "bounds": [0.5, 0.95]},
        {"name": "chromium", "type": "continuous", "bounds": [0.05, 0.3]},
        {"name": "nickel", "type": "continuous", "bounds": [0.0, 0.2]},
    ],
    objectives=[
        {"name": "hardness", "direction": "maximize"},
        {"name": "corrosion_resistance", "direction": "maximize"},
    ],
    constraints=[
        {"type": "sum_equals", "components": ["iron", "chromium", "nickel"], "value": 1.0},
    ],
)

# 2. Load seed data
import pandas as pd
data = pd.read_csv("initial_measurements.csv")
material.add_data(data)

# 3. Configure and run campaign
campaign = Campaign(
    material=material,
    surrogate=MLPSurrogate(hidden_layers=[64, 64]),
    optimizer=CMAESOptimizer(sigma0=0.3),
    max_iterations=20,
    batch_size=5,
)

# Run the full optimization loop
results = campaign.run()

# 4. Analyze results
print(results.best_candidates(n=10))
print(results.pareto_front())
results.plot_convergence()  # Renders in Jupyter or saves to file
```

## Connecting to a Remote Server

```python
from materia import Client

client = Client(
    base_url="https://api.matcraft.ai/api/v1",
    token="mc_live_abc123...",
)

# List existing campaigns
campaigns = client.campaigns.list()

# Create a new campaign on the server
campaign = client.campaigns.create(
    material_id="mat-001",
    max_iterations=20,
)

# Stream real-time updates
for event in client.campaigns.stream(campaign.id):
    print(f"Iteration {event.iteration}: best = {event.best_value}")
```

## Key SDK Classes

| Class | Purpose |
|-------|---------|
| `Material` | Define components, objectives, constraints |
| `Campaign` | Orchestrate the optimization loop |
| `MLPSurrogate` | Neural network surrogate model |
| `CMAESOptimizer` | CMA-ES optimization strategy |
| `ActiveLearningLoop` | Acquisition-driven iteration |
| `Client` | Remote API client |

The SDK is fully typed with comprehensive docstrings. Use your IDE's autocomplete or run `help(Campaign)` in a Python REPL for detailed parameter documentation.

Question 17

What is CMA-ES and why does MatCraft use it?

Accepted Answer

CMA-ES (Covariance Matrix Adaptation Evolution Strategy) is a derivative-free optimization algorithm that excels at solving non-convex, noisy, and multi-modal optimization problems. It is the default optimizer in MatCraft and is particularly well-suited for materials optimization.

## How CMA-ES Works

CMA-ES maintains a multivariate normal distribution over the search space and iteratively updates it to concentrate probability mass around promising regions:

1. **Sample**: Generate a population of candidate solutions from the current distribution.
2. **Evaluate**: Score each candidate using the surrogate model (or a physics evaluator).
3. **Select**: Rank candidates by fitness and select the top performers.
4. **Update**: Adapt the mean and covariance matrix of the distribution based on the selected candidates. The covariance matrix captures correlations between parameters, enabling the algorithm to learn the "shape" of the fitness landscape.

## Why CMA-ES for Materials

- **No gradients required**: Materials objectives are often non-differentiable (e.g., outputs from simulations or physical experiments). CMA-ES works purely from function evaluations.
- **Handles correlations**: Material components are frequently correlated (e.g., increasing one filler reduces the fraction available for another). The covariance matrix naturally captures these relationships.
- **Noise-tolerant**: Experimental measurements are inherently noisy. CMA-ES uses population-based sampling that smooths out noise.
- **Self-adapting step size**: The algorithm automatically adjusts its exploration radius -- searching broadly early on and narrowing as it converges.

## Configuration in MatCraft

```yaml
optimizer:
  type: cma-es
  sigma0: 0.3          # Initial step size (fraction of parameter range)
  population_size: 20  # Candidates per generation (default: 4 + 3*ln(n))
  max_generations: 100 # Safety limit per iteration
```

`sigma0` is the most important hyperparameter. A value of 0.3 means the initial search covers roughly 30% of each parameter's range. Start with 0.3 and decrease to 0.1 if you have a good prior on where the optimum lies.

## Comparison to Alternatives

CMA-ES outperforms random search, grid search, and simple genetic algorithms on problems with 3-50 parameters. For very high-dimensional problems (>100 parameters), consider the separable CMA-ES variant (`type: sep-cma-es`) which scales more efficiently.

Question 18

How do surrogate models work in MatCraft?

Accepted Answer

Surrogate models are lightweight machine learning models that approximate expensive-to-evaluate functions. In MatCraft, they replace costly physics simulations or physical experiments during the optimization loop, enabling the optimizer to evaluate thousands of candidate compositions in seconds.

## The Role of Surrogates

In a typical materials optimization pipeline without surrogates, each evaluation might require:

- A DFT calculation (hours to days per composition)
- A molecular dynamics simulation (minutes to hours)
- A physical experiment (days to weeks)

A trained surrogate model can approximate these evaluations in **milliseconds**, enabling the CMA-ES optimizer to explore the design space efficiently.

## MLP Surrogate (Default)

MatCraft's default surrogate is a multi-layer perceptron (MLP) neural network:

```python
from materia.surrogate import MLPSurrogate

surrogate = MLPSurrogate(
    hidden_layers=[64, 64],   # Two hidden layers with 64 neurons each
    activation="relu",         # ReLU activation function
    learning_rate=0.001,       # Adam optimizer learning rate
    epochs=200,                # Training epochs
    validation_split=0.2,      # 20% held out for validation
    early_stopping_patience=20 # Stop if validation loss plateaus
)
```

The MLP takes component values as input and predicts objective values as output. For multi-objective problems, a separate output head is trained for each objective.

## Training Pipeline

1. **Normalization**: Input features are standardized to zero mean and unit variance. Objectives are min-max scaled.
2. **Training**: The MLP is trained using the Adam optimizer with mean squared error loss. Early stopping prevents overfitting on small datasets.
3. **Uncertainty estimation**: MatCraft uses MC Dropout or an ensemble of models to estimate prediction uncertainty. This uncertainty is critical for the active learning acquisition function.
4. **Retraining**: After each active learning iteration adds new data, the surrogate is retrained from scratch (not fine-tuned) to avoid catastrophic forgetting.

## When Surrogates Struggle

- **Very small datasets** (<10 points): The surrogate may not have enough data to learn meaningful patterns. Consider starting with a space-filling design (Latin Hypercube).
- **Highly discontinuous objectives**: MLPs assume some smoothness. If your objective has sharp phase transitions, increase network depth or consider a Gaussian Process surrogate.
- **Extrapolation**: Surrogates are less reliable outside the range of training data. MatCraft's acquisition function accounts for this by penalizing high-uncertainty regions.

Question 19

What is active learning and how does MatCraft use it?

Accepted Answer

Active learning is a machine learning strategy where the model actively selects which data points to learn from next, rather than passively receiving a fixed dataset. In MatCraft, active learning drives the optimization loop by choosing the most informative compositions to evaluate, minimizing the total number of expensive experiments needed.

## The Active Learning Loop

MatCraft's active learning loop follows this cycle:

```
Seed Data -> Train Surrogate -> Acquisition Function -> Select Candidates
    ^                                                        |
    |                                                        v
    +-------------- Evaluate & Add Data <------- Top-K Candidates
```

1. **Train surrogate**: Fit the MLP on all available data.
2. **Generate candidates**: Use CMA-ES to optimize the acquisition function, producing a large set of promising candidates.
3. **Rank by acquisition**: Score each candidate using the acquisition function, which balances predicted performance (exploitation) with prediction uncertainty (exploration).
4. **Select top-K**: Choose the top `batch_size` candidates for evaluation.
5. **Evaluate**: Run the candidates through your physics model, simulation, or flag them for experimental validation.
6. **Add data**: Incorporate the new measurements and repeat.

## Acquisition Functions

MatCraft supports several acquisition functions:

- **Expected Improvement (EI)**: The default. Measures the expected amount by which a candidate improves over the current best. Good general-purpose choice.
- **Upper Confidence Bound (UCB)**: Adds a weighted uncertainty bonus to the predicted value. The `exploration_weight` parameter (kappa) controls the exploration-exploitation trade-off.
- **Probability of Improvement (PI)**: Measures the probability that a candidate beats the current best. More conservative than EI.
- **Thompson Sampling**: Samples from the surrogate's posterior distribution. Naturally balances exploration and exploitation.

```yaml
acquisition:
  type: expected_improvement
  exploration_weight: 0.1  # Only used for UCB; ignored for EI
```

## Why Active Learning Matters

Without active learning, you might need 500+ experiments to find a near-optimal composition in a 5D space. With active learning, MatCraft typically finds competitive solutions in 50-100 total evaluations (10-20 seed + 5-15 iterations of batch size 5). This represents a 5-10x reduction in experimental cost, which translates directly to saved time and money in a lab setting.

## Convergence

The loop terminates when the convergence criterion is met (e.g., no improvement for N consecutive iterations) or the maximum iteration count is reached.

Question 20

What is a Pareto front and how does MatCraft compute it?

Accepted Answer

A Pareto front (also called a Pareto frontier) is the set of solutions where no objective can be improved without worsening at least one other objective. It represents the optimal trade-off surface in multi-objective optimization.

## Intuitive Example

Consider optimizing a water membrane for two objectives:

- **Maximize water flux** (how fast water passes through)
- **Maximize salt rejection** (how effectively salt is blocked)

These objectives typically conflict: membranes with high flux tend to have lower rejection, and vice versa. The Pareto front is the curve of compositions where you cannot increase flux without decreasing rejection.

## How MatCraft Computes It

MatCraft uses a non-dominated sorting approach:

1. **Collect all evaluated candidates** across all iterations of the campaign.
2. **Non-dominated sorting**: A candidate A *dominates* candidate B if A is at least as good as B on all objectives and strictly better on at least one. Candidates that are not dominated by any other candidate form the Pareto front.
3. **Crowding distance**: Among Pareto-optimal solutions, MatCraft computes a crowding distance metric to ensure a well-distributed spread along the front.

```python
from materia.analysis import compute_pareto_front

# Get the Pareto front from campaign results
front = compute_pareto_front(campaign.results)
print(f"Found {len(front)} Pareto-optimal solutions")

for candidate in front:
    print(f"  Flux: {candidate.water_flux:.1f}, Rejection: {candidate.salt_rejection:.1f}%")
```

## Visualization

The MatCraft dashboard provides interactive Pareto plots:

- **2D Pareto plot**: For two objectives, the front is displayed as a curve with candidate points. Click any point to see the full composition.
- **3D Pareto plot**: For three objectives, an interactive 3D surface is rendered.
- **Parallel coordinates**: For four or more objectives, a parallel coordinates plot shows trade-offs across all objectives simultaneously.

## Using the Pareto Front

The Pareto front does not give you a single "best" answer -- it gives you the set of optimal trade-offs. Choosing among Pareto-optimal solutions is a domain decision:

- A water treatment plant might prioritize rejection over flux.
- A desalination startup might prioritize flux to reduce membrane area and cost.

MatCraft lets you apply preference weights or knee-point detection to highlight the most balanced solution on the front.

Question 21

How does MatCraft determine when optimization has converged?

Accepted Answer

Convergence detection is how MatCraft decides when to stop the optimization loop. Running too few iterations risks missing the optimum; running too many wastes computational and experimental resources.

## Convergence Criteria

MatCraft supports multiple convergence criteria, which can be combined:

### 1. Improvement Patience (Default)

The campaign stops if the best objective value has not improved by more than a threshold for a specified number of consecutive iterations:

```yaml
convergence:
  patience: 5            # Stop after 5 iterations without improvement
  min_improvement: 0.01  # Minimum relative improvement to count as progress
```

For multi-objective campaigns, "improvement" is measured by the hypervolume indicator of the Pareto front -- the volume of objective space dominated by the current front relative to a reference point.

### 2. Absolute Target

Stop when a target objective value is reached:

```yaml
convergence:
  target:
    water_flux: 50.0        # Stop when flux >= 50
    salt_rejection: 95.0    # AND rejection >= 95%
```

### 3. Maximum Iterations

A hard cap that always applies:

```yaml
campaign:
  max_iterations: 30  # Never run more than 30 iterations
```

### 4. Surrogate Stability

Stop when the surrogate model's predictions stabilize -- measured by the mean absolute change in predictions on a held-out validation set between consecutive iterations:

```yaml
convergence:
  surrogate_stability: 0.005  # Stop when predictions change < 0.5%
```

## Monitoring Convergence

The dashboard and CLI display a real-time convergence plot showing:

- **Best objective value** (or hypervolume) per iteration
- **Surrogate validation error** per iteration
- **Acquisition function maximum** per iteration (indicates how much the model thinks there is to gain)

A declining acquisition maximum is a strong signal that the search space has been well-explored.

## Recommendations

- For exploratory campaigns with cheap evaluations, set a high `max_iterations` (50+) and rely on patience-based stopping.
- For expensive experiments (physical lab work), set a conservative `max_iterations` (10-15) and manually review candidates at each iteration before approving evaluation.
- The default `patience=5, min_improvement=0.01` works well for most problems with 3-10 parameters.

Question 22

How does multi-objective optimization work in MatCraft?

Accepted Answer

Multi-objective optimization (MOO) is the process of simultaneously optimizing two or more conflicting objectives. Most real-world materials problems are inherently multi-objective -- you want a material that is strong *and* lightweight, or conductive *and* cheap.

## MatCraft's Approach

MatCraft handles multi-objective optimization through a combination of surrogate models, scalarization, and Pareto analysis:

### 1. Per-Objective Surrogates

A separate surrogate model (or output head) is trained for each objective. This means the model independently predicts water flux, salt rejection, and cost for a given composition. Each surrogate has its own uncertainty estimate.

### 2. Scalarization for CMA-ES

CMA-ES natively optimizes a single scalar value. MatCraft converts multiple objectives into a scalar using one of these strategies:

- **Weighted sum**: `score = w1 * obj1_normalized + w2 * obj2_normalized`. Simple but can miss concave regions of the Pareto front.
- **Chebyshev scalarization** (default): Minimizes the worst-case weighted deviation from the ideal point. This can find solutions in concave regions and produces a more uniform Pareto front.
- **Random weight sampling**: On each iteration, random weight vectors are sampled. Over many iterations, this covers the full Pareto front.

```yaml
objectives:
  - name: hardness
    direction: maximize
    weight: 0.6    # Optional; used for weighted scalarization
  - name: cost
    direction: minimize
    weight: 0.4
```

### 3. Hypervolume-Based Acquisition

For the active learning loop, the acquisition function is extended to multi-objective settings using the **Expected Hypervolume Improvement (EHVI)**. This measures how much a new candidate would expand the dominated volume of the Pareto front, naturally balancing all objectives.

### 4. Pareto Front Construction

After the campaign completes (or at any intermediate point), MatCraft extracts the Pareto front from all evaluated candidates. The front is available as a DataFrame, a plot, or an interactive visualization.

```python
results = campaign.run()

# Get Pareto-optimal candidates
pareto = results.pareto_front()
print(pareto[["hardness", "cost", "iron", "chromium", "nickel"]])

# Find the "knee" point -- the solution with the best balance
knee = results.pareto_knee()
print(f"Balanced solution: {knee}")
```

## Number of Objectives

MatCraft supports 2-6 objectives efficiently. Beyond 6 objectives, the Pareto front becomes very large (most solutions are non-dominated in high dimensions), and the hypervolume computation becomes expensive. For many-objective problems (>6), consider grouping related objectives or using preference-based scalarization.

Question 23

Can I define custom objective functions?

Accepted Answer

Yes. MatCraft supports custom objective functions for cases where the built-in domain physics models do not cover your needs. You can define objectives as Python functions, external scripts, or API endpoints.

## Python Function Evaluator

The most common approach is to write a Python function that takes a composition dictionary and returns objective values:

```python
from materia.evaluate import Evaluator
from materia import Campaign, Material

class MyEvaluator(Evaluator):
    """Custom evaluator for polymer blend properties."""

def evaluate(self, composition: dict) -> dict:
        # Your custom logic here
        polymer_a = composition["polymer_a_fraction"]
        polymer_b = composition["polymer_b_fraction"]
        filler = composition["filler_loading"]

# Could be an analytical model, a simulation call, or a lookup
        tensile_strength = self._run_simulation(polymer_a, polymer_b, filler)
        elongation = 150 - 200 * filler + 50 * polymer_b
        cost = 10 * polymer_a + 25 * polymer_b + 5 * filler

return {
            "tensile_strength": tensile_strength,
            "elongation_at_break": elongation,
            "material_cost": cost,
        }

def _run_simulation(self, a, b, f):
        # Call your simulation code, external binary, or API
        import subprocess
        result = subprocess.run(
            ["./my_sim", str(a), str(b), str(f)],
            capture_output=True, text=True
        )
        return float(result.stdout.strip())

material = Material.from_yaml("my_blend.yaml")
campaign = Campaign(
    material=material,
    evaluator=MyEvaluator(),
    max_iterations=15,
)
campaign.run()
```

## Analytic Evaluator

For simple closed-form expressions, use the built-in analytic evaluator without writing a class:

```yaml
evaluator:
  type: analytic
  expressions:
    tensile_strength: "120 * polymer_a + 80 * polymer_b + 200 * filler"
    cost: "10 * polymer_a + 25 * polymer_b + 5 * filler"
```

## External API Evaluator

If your simulation runs as a web service:

```yaml
evaluator:
  type: http
  url: "https://my-simulation-server.com/evaluate"
  method: POST
  headers:
    Authorization: "Bearer ${SIM_API_TOKEN}"
  timeout: 300  # seconds
```

MatCraft will POST the composition as JSON and expect a JSON response with objective values.

## Human-in-the-Loop

For physical experiments, set the evaluator to `manual`. The campaign will pause at each iteration, display the proposed candidates on the dashboard, and wait for you to enter measured values before continuing:

```yaml
evaluator:
  type: manual
```

This is the recommended mode for lab-based optimization where each "evaluation" is a physical experiment.

Question 24

How do I tune hyperparameters for better optimization results?

Accepted Answer

MatCraft's defaults work well for most problems, but tuning key hyperparameters can improve convergence speed and solution quality. Here is a guide to the most impactful settings.

## Surrogate Model Hyperparameters

### Hidden Layers

```yaml
surrogate:
  hidden_layers: [64, 64]  # Default
```

- **Small datasets (<50 points)**: Use `[32, 32]` or even `[32]` to avoid overfitting.
- **Large datasets (>200 points)**: Scale up to `[128, 128]` or `[128, 64, 32]`.
- **High-dimensional inputs (>10 parameters)**: Add a wider first layer, e.g., `[128, 64]`.

### Learning Rate and Epochs

```yaml
surrogate:
  learning_rate: 0.001  # Default. Decrease to 0.0005 for noisy data.
  epochs: 200           # Default. Increase to 500 for complex objectives.
  early_stopping_patience: 20  # Prevents overfitting
```

### Ensemble Size

Using an ensemble of surrogates provides better uncertainty estimates for the acquisition function:

```yaml
surrogate:
  ensemble_size: 5  # Train 5 independent MLPs (default: 1 with MC Dropout)
```

Ensembles are more expensive to train but significantly improve active learning performance on small datasets.

## Optimizer Hyperparameters

### CMA-ES Settings

```yaml
optimizer:
  sigma0: 0.3           # Start broad; decrease to 0.1 if you have a good prior
  population_size: 20   # Increase for noisy objectives or high dimensions
```

- **sigma0**: The initial step size relative to parameter ranges. Use 0.3 for exploratory searches, 0.1 when you have a rough idea of the optimal region.
- **population_size**: Larger populations are more robust but slower. The default of `4 + floor(3 * ln(n_params))` is usually good. Double it for very noisy problems.

## Acquisition Function

```yaml
acquisition:
  type: expected_improvement  # Best default
  # type: upper_confidence_bound
  # exploration_weight: 2.0   # Higher = more exploration
```

- **EI** is the best default for most problems.
- **UCB** with a high `exploration_weight` (2.0-5.0) is useful when you suspect the design space has multiple local optima and want to explore more broadly.

## Batch Size

```yaml
campaign:
  batch_size: 5  # Candidates per iteration
```

- **Cheap evaluations** (simulations, analytic models): Use batch size 1 for maximum sample efficiency.
- **Expensive evaluations** (lab experiments): Use batch size 5-10 to maximize parallelism.
- Larger batches reduce the number of iterations but may explore less efficiently per evaluation.

## Quick Tuning Checklist

1. Start with defaults and run a baseline campaign.
2. Check the convergence plot. If the surrogate error is high, increase network size or ensemble count.
3. If convergence is slow, increase `sigma0` or switch to UCB with higher exploration weight.
4. If the surrogate overfits (training error low, validation error high), reduce network size or increase early stopping patience.

Question 25

What material domains does MatCraft support?

Accepted Answer

MatCraft ships with 16 built-in material domain plugins, each providing pre-configured parameter schemas, physics models, and validation rules specific to that material class. You can also create custom domains for materials not covered by the built-in plugins.

## Built-In Domains

| Domain | Key Parameters | Typical Objectives |
|--------|---------------|-------------------|
| **Water Membranes** | Polymer type, concentration, additives, pore size | Water flux, salt rejection, fouling resistance |
| **Lithium-Ion Batteries** | Cathode composition (NMC ratios), electrolyte, coating | Capacity, cycle life, rate capability |
| **Sodium-Ion Batteries** | Cathode chemistry, electrolyte formulation | Capacity, voltage, cycle stability |
| **Perovskite Solar Cells** | A/B/X-site composition, layer thicknesses | Power conversion efficiency, stability |
| **Silicon Solar Cells** | Doping profiles, texturing, anti-reflection coating | Efficiency, cost per watt |
| **Thermoelectrics** | Carrier concentration, alloying fractions | ZT (figure of merit), power factor |
| **Catalysts** | Metal loadings, support material, promoters | Activity, selectivity, stability |
| **Polymer Composites** | Matrix resin, filler type and loading, fiber orientation | Tensile strength, modulus, impact resistance |
| **Ceramic Coatings** | Composition, deposition temperature, thickness | Hardness, thermal conductivity, adhesion |
| **Alloys** | Elemental fractions, heat treatment parameters | Yield strength, ductility, corrosion resistance |
| **Superconductors** | Elemental ratios, doping levels | Critical temperature (Tc), critical current |
| **Magnetic Materials** | Rare earth content, microstructure parameters | Coercivity, remanence, energy product |
| **Optical Films** | Layer compositions, thicknesses | Transmittance, reflectance, bandwidth |
| **Biomaterials** | Polymer blend ratios, crosslinker, growth factors | Biocompatibility, degradation rate, mechanical properties |
| **Concrete & Cement** | Cement type, aggregate ratio, admixtures | Compressive strength, workability, CO2 footprint |
| **Electronic Packaging** | Solder composition, underfill, substrate | Thermal conductivity, CTE match, reliability |

## Using a Domain Plugin

Specify the domain in your material YAML to activate domain-specific features:

```yaml
domain: battery
```

This enables automatic parameter validation (e.g., ensuring NMC fractions sum to 1.0), domain-specific physics models for fast approximate evaluation, and curated default parameter ranges based on published literature.

## Custom Domains

If your material is not covered, you can define a custom domain or use the generic `custom` domain with no built-in physics. See the "How to create a custom domain" FAQ for details.

Question 26

How do I optimize water purification membranes with MatCraft?

Accepted Answer

The water membrane domain is one of MatCraft's most mature plugins. It supports optimization of polymeric membranes for reverse osmosis (RO), nanofiltration (NF), and ultrafiltration (UF) applications.

## Quick Start

```yaml
name: "ro-membrane-study"
domain: water_membrane

components:
  - name: polymer_concentration
    type: continuous
    bounds: [0.10, 0.35]
    unit: "wt%"
    description: "Polymer (PSf/PES/PVDF) concentration in casting solution"
  - name: additive_type
    type: categorical
    choices: ["PVP", "PEG", "LiCl", "ZnCl2", "none"]
  - name: additive_concentration
    type: continuous
    bounds: [0.0, 0.15]
    unit: "wt%"
  - name: coagulation_bath_temp
    type: continuous
    bounds: [15, 60]
    unit: "°C"
  - name: evaporation_time
    type: continuous
    bounds: [0, 120]
    unit: "seconds"

objectives:
  - name: water_flux
    direction: maximize
    unit: "L/m²/h"
  - name: salt_rejection
    direction: maximize
    unit: "%"
  - name: fouling_resistance
    direction: maximize
    unit: "FRR%"
    description: "Flux recovery ratio after BSA fouling"

constraints:
  - type: custom
    expression: "salt_rejection >= 90.0"
    description: "Minimum acceptable rejection for RO"
```

## Built-In Physics Model

The water membrane plugin includes a simplified transport model based on the solution-diffusion framework:

- **Water flux** is estimated using the Hagen-Poiseuille equation with porosity and pore size derived from polymer concentration and additive effects.
- **Salt rejection** is modeled using the Kedem-Katchalsky equation, accounting for membrane thickness and charge effects.
- **Fouling resistance** uses empirical correlations based on surface hydrophilicity (influenced by additive type).

These physics models provide approximate evaluations for surrogate training when you do not have experimental data for every candidate. They are calibrated against published literature data for common PSf/PES systems.

## Typical Results

In our benchmarks with PSf membranes, MatCraft found Pareto-optimal compositions that matched or exceeded manually optimized formulations from the literature within 12 iterations (60 total evaluations including 20 seed points). The key insight from the optimization was a non-obvious interaction between additive concentration and coagulation temperature that was not captured by one-variable-at-a-time experiments.

## Experimental Workflow

For lab-based optimization, set the evaluator to `manual` mode. MatCraft will suggest 5 compositions per iteration, you fabricate and test them, enter the results, and the next iteration refines the search.

Question 27

How do I design battery materials with MatCraft?

Accepted Answer

MatCraft's battery domain plugin supports optimization of cathode compositions, electrolyte formulations, and electrode architectures for lithium-ion and sodium-ion batteries.

## Cathode Composition Optimization (NMC)

The most common use case is optimizing Ni-Mn-Co ratios in layered oxide cathodes:

```yaml
name: "nmc-cathode-opt"
domain: battery

components:
  - name: nickel_fraction
    type: continuous
    bounds: [0.33, 0.95]
    description: "Ni molar fraction"
  - name: manganese_fraction
    type: continuous
    bounds: [0.025, 0.34]
  - name: cobalt_fraction
    type: continuous
    bounds: [0.025, 0.34]
  - name: coating_thickness
    type: continuous
    bounds: [0.5, 15.0]
    unit: "nm"
    description: "Al2O3 surface coating thickness"
  - name: calcination_temp
    type: continuous
    bounds: [700, 900]
    unit: "°C"

constraints:
  - type: sum_equals
    components: [nickel_fraction, manganese_fraction, cobalt_fraction]
    value: 1.0

objectives:
  - name: specific_capacity
    direction: maximize
    unit: "mAh/g"
  - name: capacity_retention_500
    direction: maximize
    unit: "%"
    description: "Capacity retention after 500 cycles at 1C"
  - name: cobalt_content
    direction: minimize
    description: "Minimize cobalt for cost and ethics"
```

## Built-In Physics

The battery plugin includes:

- **Thermodynamic model**: Predicts theoretical capacity from composition using ionic radii and oxidation state analysis.
- **Empirical cycle life model**: Estimates capacity fade based on Ni content (higher Ni = faster degradation) and coating thickness (thicker coating = slower degradation but lower initial capacity).
- **Cost model**: Calculates raw material cost per kg based on current commodity prices for Ni, Mn, and Co.

## Electrolyte Optimization

```yaml
domain: battery
components:
  - name: ec_fraction
    type: continuous
    bounds: [0.1, 0.5]
    description: "Ethylene carbonate volume fraction"
  - name: dmc_fraction
    type: continuous
    bounds: [0.2, 0.7]
  - name: emc_fraction
    type: continuous
    bounds: [0.0, 0.5]
  - name: lipf6_concentration
    type: continuous
    bounds: [0.8, 1.5]
    unit: "mol/L"
  - name: vc_additive
    type: continuous
    bounds: [0.0, 0.05]
    description: "Vinylene carbonate additive fraction"

constraints:
  - type: sum_equals
    components: [ec_fraction, dmc_fraction, emc_fraction]
    value: 1.0

objectives:
  - name: ionic_conductivity
    direction: maximize
    unit: "mS/cm"
  - name: electrochemical_window
    direction: maximize
    unit: "V"
```

## Integration with DFT

For high-fidelity evaluations, MatCraft can wrap DFT codes (VASP, Quantum ESPRESSO) as external evaluators. The surrogate model learns from DFT results and reduces the total number of expensive calculations needed by 5-10x compared to brute-force screening.

Question 28

How do I optimize solar cell materials with MatCraft?

Accepted Answer

MatCraft supports optimization of both perovskite and silicon solar cells. The solar cell domain plugin provides physics models for predicting power conversion efficiency and stability from material parameters.

## Perovskite Solar Cells

Perovskite absorbers have the general formula ABX3, where A, B, and X site compositions dramatically affect performance:

```yaml
name: "perovskite-absorber"
domain: solar_cell

components:
  - name: ma_fraction
    type: continuous
    bounds: [0.0, 1.0]
    description: "Methylammonium (MA) fraction on A-site"
  - name: fa_fraction
    type: continuous
    bounds: [0.0, 1.0]
    description: "Formamidinium (FA) fraction on A-site"
  - name: cs_fraction
    type: continuous
    bounds: [0.0, 0.2]
    description: "Cesium fraction on A-site"
  - name: pb_fraction
    type: continuous
    bounds: [0.5, 1.0]
    description: "Lead fraction on B-site"
  - name: sn_fraction
    type: continuous
    bounds: [0.0, 0.5]
    description: "Tin fraction on B-site"
  - name: iodide_fraction
    type: continuous
    bounds: [0.5, 1.0]
    description: "Iodide fraction on X-site"
  - name: bromide_fraction
    type: continuous
    bounds: [0.0, 0.5]
  - name: absorber_thickness
    type: continuous
    bounds: [200, 800]
    unit: "nm"

constraints:
  - type: sum_equals
    components: [ma_fraction, fa_fraction, cs_fraction]
    value: 1.0
  - type: sum_equals
    components: [pb_fraction, sn_fraction]
    value: 1.0
  - type: sum_equals
    components: [iodide_fraction, bromide_fraction]
    value: 1.0

objectives:
  - name: pce
    direction: maximize
    unit: "%"
    description: "Power conversion efficiency"
  - name: stability_t80
    direction: maximize
    unit: "hours"
    description: "Time to 80% of initial efficiency under 1-sun illumination"
  - name: bandgap
    direction: minimize
    description: "Deviation from Shockley-Queisser optimal bandgap (1.34 eV)"
```

## Built-In Physics

The solar cell plugin includes:

- **Bandgap estimation**: Vegard's law interpolation from end-member bandgaps, accounting for bowing parameters for mixed compositions.
- **Shockley-Queisser limit**: Theoretical maximum efficiency as a function of bandgap.
- **Stability heuristic**: Empirical model based on Goldschmidt tolerance factor and octahedral factor -- compositions with tolerance factors closer to 1.0 are predicted to be more stable.
- **Absorption coefficient model**: Estimates absorption edge and Urbach energy from composition.

## Typical Campaign

A perovskite optimization campaign with 8 parameters typically converges in 15-20 iterations. The Pareto front between efficiency and stability reveals the fundamental trade-off: Sn-rich compositions can achieve high efficiency but suffer from rapid oxidation, while Cs-containing compositions are more stable but have wider bandgaps.

## Silicon Solar Cells

For silicon cells, the domain covers doping profiles, surface texturing parameters, anti-reflection coating thickness, and metallization geometry. The physics model uses a simplified PC1D-style simulation for rapid efficiency estimation.

Question 29

How do I create a custom material domain?

Accepted Answer

If your material is not covered by MatCraft's 16 built-in domains, you can create a custom domain plugin. A domain plugin consists of a YAML schema definition and an optional Python physics module.

## Minimal Custom Domain

At minimum, a domain is a YAML file defining the parameter schema:

```yaml
# plugins/my_domain/components.yaml
domain_name: shape_memory_alloy
description: "NiTi-based shape memory alloys"
version: "1.0.0"

default_components:
  - name: nickel_content
    type: continuous
    bounds: [49.0, 51.5]
    unit: "at%"
    description: "Nickel atomic percentage"
  - name: aging_temperature
    type: continuous
    bounds: [300, 600]
    unit: "°C"
  - name: aging_time
    type: continuous
    bounds: [0.5, 48]
    unit: "hours"
  - name: cold_work
    type: continuous
    bounds: [0, 40]
    unit: "%"

default_objectives:
  - name: transformation_temperature
    direction: maximize
    unit: "°C"
    description: "Austenite finish temperature (Af)"
  - name: recoverable_strain
    direction: maximize
    unit: "%"
  - name: fatigue_life
    direction: maximize
    unit: "cycles"

default_constraints:
  - type: custom
    expression: "nickel_content >= 49.5 and nickel_content <= 51.0"
    description: "Near-equiatomic NiTi range for shape memory effect"
```

## Adding a Physics Model

Create a Python file with evaluation functions:

```python
# plugins/my_domain/physics.py
from materia.evaluate import DomainPhysics

class ShapeMemoryAlloyPhysics(DomainPhysics):
    """Physics model for NiTi shape memory alloys."""

def evaluate(self, composition: dict) -> dict:
        ni = composition["nickel_content"]
        t_age = composition["aging_temperature"]
        t_time = composition["aging_time"]
        cw = composition["cold_work"]

# Empirical model for transformation temperature
        # Based on Frenzel et al. (2010) correlations
        af = -1450 + 28.5 * ni + 0.02 * t_age * t_time - 0.5 * cw

# Recoverable strain model
        strain = 8.0 - 0.15 * abs(ni - 50.5) - 0.01 * cw

# Fatigue life (log-linear model)
        import math
        fatigue = math.exp(10 - 0.5 * abs(ni - 50.0) + 0.01 * t_age - 0.02 * cw)

return {
            "transformation_temperature": af,
            "recoverable_strain": max(0, strain),
            "fatigue_life": fatigue,
        }
```

## Registering the Plugin

Place your files in the plugin directory and register them:

```bash
materia plugin register ./plugins/my_domain/
```

Or in Python:

```python
from materia.plugins import register_domain
register_domain("./plugins/my_domain/")
```

## Using Your Custom Domain

```yaml
domain: shape_memory_alloy  # References your registered plugin
name: "niti-optimization"
# Components and objectives inherit from plugin defaults
# Override or add additional parameters as needed
components:
  - name: ternary_element
    type: categorical
    choices: ["Cu", "Fe", "Nb", "none"]
```

## Best Practices

- Start with published empirical correlations for your physics model, even if approximate. The surrogate will learn corrections from real data.
- Include sensible default bounds based on literature. Users can always override them.
- Add input validation to catch physically impossible combinations early.
- Write unit tests for your physics model to catch regressions.

Question 30

How do I add custom physics models to a domain?

Accepted Answer

Physics models in MatCraft serve as fast approximate evaluators that supplement or replace experimental data during optimization. They are particularly valuable for generating initial training data for the surrogate model.

## Physics Model Architecture

A physics model inherits from `DomainPhysics` and implements the `evaluate` method:

```python
from materia.evaluate import DomainPhysics
import numpy as np

class MyPhysicsModel(DomainPhysics):
    """Custom physics model for thermal barrier coatings."""

def __init__(self, temperature: float = 1000.0):
        super().__init__()
        self.operating_temp = temperature  # Service temperature in °C

def evaluate(self, composition: dict) -> dict:
        ysz_fraction = composition["ysz_fraction"]
        alumina_fraction = composition["alumina_fraction"]
        thickness = composition["coating_thickness"]
        porosity = composition["porosity"]

# Thermal conductivity (Maxwell-Eucken model)
        k_dense = 2.5 * ysz_fraction + 30.0 * alumina_fraction
        k_eff = k_dense * (1 - porosity) / (1 + 0.5 * porosity)

# Thermal resistance
        r_thermal = thickness * 1e-6 / k_eff  # m²·K/W

# Thermal stress (simplified Timoshenko)
        delta_t = self.operating_temp - 25.0
        cte_mismatch = abs(10e-6 * ysz_fraction - 12e-6 * alumina_fraction)
        thermal_stress = cte_mismatch * delta_t * 200e9 * thickness * 1e-6

# Erosion resistance (empirical)
        erosion_rate = 0.1 / (ysz_fraction * thickness * (1 - porosity) + 0.01)

return {
            "thermal_resistance": r_thermal,
            "thermal_stress": thermal_stress,
            "erosion_rate": erosion_rate,
        }

def validate_inputs(self, composition: dict) -> list[str]:
        """Optional: return list of validation warnings."""
        warnings = []
        if composition.get("porosity", 0) > 0.3:
            warnings.append("Porosity > 30% may compromise structural integrity")
        return warnings
```

## Wrapping External Simulation Codes

If you have an existing simulation tool (COMSOL, LAMMPS, VASP, etc.), wrap it as a physics model:

```python
import subprocess
import json
from materia.evaluate import DomainPhysics

class COMSOLWrapper(DomainPhysics):
    def __init__(self, comsol_path: str, model_file: str):
        super().__init__()
        self.comsol_path = comsol_path
        self.model_file = model_file

def evaluate(self, composition: dict) -> dict:
        # Write input parameters
        with open("/tmp/comsol_input.json", "w") as f:
            json.dump(composition, f)

# Run COMSOL in batch mode
        result = subprocess.run(
            [self.comsol_path, "batch", "-inputfile", self.model_file,
             "-paramfile", "/tmp/comsol_input.json",
             "-outputfile", "/tmp/comsol_output.json"],
            capture_output=True, text=True, timeout=3600
        )

if result.returncode != 0:
            raise RuntimeError(f"COMSOL failed: {result.stderr}")

with open("/tmp/comsol_output.json") as f:
            return json.load(f)
```

## Hybrid Evaluation

MatCraft supports a hybrid approach where fast physics models provide most evaluations, and expensive simulations or experiments are used selectively:

```python
campaign = Campaign(
    material=material,
    evaluator=MyPhysicsModel(),          # Fast approximate model
    validation_evaluator=COMSOLWrapper(),  # Expensive high-fidelity model
    validation_frequency=5,  # Validate every 5th candidate with COMSOL
)
```

This two-tier approach gives you the speed of approximate models with periodic ground-truth validation.

Question 31

How do material domain parameters work?

Accepted Answer

Domain parameters define the search space for your optimization campaign. Understanding parameter types, bounds, and constraints is essential for setting up an effective campaign.

## Parameter Types

MatCraft supports three parameter types:

### Continuous

Real-valued parameters with lower and upper bounds. This is the most common type.

```yaml
- name: temperature
  type: continuous
  bounds: [200, 800]
  unit: "°C"
```

The optimizer searches the continuous range between the bounds. CMA-ES handles continuous parameters natively.

### Discrete

Integer-valued parameters or parameters that can only take specific numeric steps:

```yaml
- name: num_layers
  type: discrete
  bounds: [1, 10]
  step: 1  # Optional, defaults to 1

- name: concentration
  type: discrete
  bounds: [0.1, 1.0]
  step: 0.1  # Only values 0.1, 0.2, ..., 1.0
```

Discrete parameters are handled by rounding the continuous CMA-ES output to the nearest valid step.

### Categorical

Parameters that take one of a fixed set of non-numeric values:

```yaml
- name: solvent
  type: categorical
  choices: ["DMF", "DMSO", "NMP", "DMAc"]
```

Categorical parameters are encoded using one-hot encoding internally. For k categories, this adds k-1 dimensions to the search space (one category is treated as the reference).

## Bounds

Bounds define the range of valid values. For best results:

- Set bounds based on **physically feasible** ranges, not just the range of your existing data.
- Wider bounds give the optimizer more room to explore but may slow convergence.
- If you know the optimum is in a specific region, tighten the bounds accordingly.

```yaml
# Too tight -- may miss the optimum
bounds: [0.48, 0.52]

# Too wide -- wastes evaluations on infeasible regions
bounds: [0.0, 1.0]

# Good -- covers the feasible range based on domain knowledge
bounds: [0.3, 0.7]
```

## Units

Units are metadata -- they do not affect the optimization. They are displayed in results and visualizations for clarity:

```yaml
- name: pressure
  bounds: [1, 100]
  unit: "bar"
```

## Default Values

You can specify a default or initial value that the optimizer uses as a starting point:

```yaml
- name: temperature
  bounds: [200, 800]
  default: 450  # CMA-ES will center initial distribution here
```

## Parameter Scaling

MatCraft automatically normalizes all parameters to [0, 1] internally for the optimizer. This ensures that parameters with different magnitudes (e.g., temperature in hundreds of degrees vs. concentration in fractional percentages) are treated equally. You do not need to manually scale your parameters.

Question 32

How do I define constraints for my material optimization?

Accepted Answer

Constraints ensure that the optimizer only proposes physically valid and feasible compositions. MatCraft supports several constraint types. ## Sum Constraints The most common constraint in materials science -- component fractions must sum to a fixed value: ```yaml constraints: - type: sum_equals components: [nickel, manganese, cobalt] value: 1.0 tolerance: 0.001 # Allow 0.1% deviation - type: sum_lte components: [filler_a, filler_b, filler_c] value: 0.4 description: "Total filler loading must not exceed 40%" ``` ## Ratio Constraints Specify that the ratio between two parameters must fall within a range: ```yaml constraints: - type: ratio_between numerator: nickel denominator: cobalt bounds: [2.0, 10.0] description: "Ni:Co ratio must be between 2:1 and 10:1" ``` ## Inequality Constraints General linear or nonlinear inequality constraints: ```yaml constraints: - type: custom expression: "temperature * pressure <= 50000" description: "Equipment safety limit" - type: custom expression: "polymer_concentration >= 2 * additive_concentration" description: "Polymer must be at least 2x the additive" ``` ## Categorical Constraints Conditional constraints that depend on categorical parameter values: ```yaml constraints: - type: conditional condition: "solvent == 'DMSO'" constraint: type: custom expression: "temperature <= 189" description: "DMSO boiling point limit" ``` ## How Constraints Are Enforced MatCraft enforces constraints at two levels: ### 1. Repair Operator (During Optimization) When CMA-ES generates a candidate that violates a constraint, a repair operator projects it back to the feasible region: - **Sum constraints**: Components are rescaled proportionally to satisfy the sum. - **Bound constraints**: Values are clamped to bounds. - **Custom constraints**: Candidates are rejected and resampled. ### 2. Validation (During Data Import) When importing experimental data, constraint violations are reported as warnings but data is not rejected. Real measurements may legitimately deviate from target constraints due to experimental error. ## Common Patterns ### Composition Simplex For materials where all components must sum to exactly 1.0: ```yaml constraints: - type: sum_equals components: [comp_a, comp_b, comp_c, comp_d] value: 1.0 ``` MatCraft uses a simplex projection to handle this efficiently -- internally reducing the dimensionality by one. ### Nested Constraints ```yaml constraints: - type: sum_equals components: [ni, mn, co] value: 1.0 - type: custom expression: "ni >= 0.33" description: "Minimum Ni content for high-energy cathode" - type: custom expression: "co <= 0.2" description: "Cap cobalt for cost reduction" ``` ## Debugging Constraints Use the CLI to check if your constraint set is feasible: ```bash materia config check-constraints my_material.yaml --samples 10000 ``` This generates 10,000 random compositions and reports what fraction satisfy all constraints. If the feasible fraction is below 1%, your constraints may be too tight.

Question 33

What is included in the free tier?

Accepted Answer

MatCraft's free tier is designed to let individual researchers and small teams evaluate the platform without any commitment. It includes everything you need to run meaningful optimization campaigns.

## Free Tier Includes

| Feature | Limit |
|---------|-------|
| Active campaigns | 3 concurrent |
| Evaluations per month | 1,000 |
| Materials | 10 |
| Data points per material | 500 |
| Surrogate model size | Up to 2 hidden layers, 128 neurons each |
| Domain plugins | All 16 built-in domains |
| Team members | 1 (individual only) |
| API access | Full REST API |
| CLI access | Full CLI |
| Data export | CSV and JSON |
| Dashboard | Full access |
| Data retention | 12 months of inactivity |

## What Counts as an Evaluation?

An "evaluation" is a single call to the surrogate model, physics model, or manual evaluation entry. In a typical campaign:

- Training the surrogate model does **not** count as evaluations.
- Each candidate composition scored by the optimizer counts as one evaluation.
- A campaign with 15 iterations and batch size 5 uses approximately 75 evaluations (plus internal optimizer evaluations, which are counted separately).

For most research projects, 1,000 evaluations per month is sufficient to run 5-10 campaigns.

## Upgrading

When you approach your limits, the dashboard shows a usage indicator. You can upgrade to Pro at any time from **Settings > Billing**. Your existing data, campaigns, and results carry over seamlessly.

## Self-Hosted

If you self-host the open-source core, there are no limits on campaigns, evaluations, or team size. The free tier limits only apply to the managed cloud service at matcraft.ai.

## Academic Users

Students and faculty at accredited institutions can apply for a free Academic tier that includes Pro-level limits. See the "Academic Discount" FAQ for details.

Question 34

What does the Pro plan include?

Accepted Answer

The Pro plan is designed for active researchers and small teams who need higher limits and collaboration features. It costs $49/month per seat (billed annually) or $59/month billed monthly.

## Pro Plan Features

| Feature | Limit |
|---------|-------|
| Active campaigns | 25 concurrent |
| Evaluations per month | 25,000 |
| Materials | Unlimited |
| Data points per material | 10,000 |
| Surrogate model size | Up to 4 hidden layers, 512 neurons each |
| Domain plugins | All 16 built-in + custom domains |
| Team members | Up to 10 |
| API access | Full REST API with higher rate limits |
| Priority support | Email with 24-hour response time |
| Data export | CSV, JSON, Excel, and Parquet |
| Integrations | Webhook notifications, Slack alerts |
| Campaign history | Unlimited retention |
| GPU training | Shared GPU pool for surrogate training |

## Collaboration Features

Pro unlocks team collaboration:

- **Shared campaigns**: Multiple team members can view and contribute to the same campaign.
- **Role-based access**: Assign Owner, Editor, or Viewer roles per campaign.
- **Activity log**: Track who made changes, added data, or launched iterations.
- **Comments**: Leave notes on specific candidates or Pareto front points.

## Comparison to Free

The biggest practical differences are:

1. **25x more evaluations**: Run larger campaigns with bigger batch sizes.
2. **Team access**: Collaborate with up to 10 colleagues.
3. **Custom domains**: Register and use your own domain plugins.
4. **GPU training**: Surrogate models train 5-10x faster on GPU.
5. **Priority support**: Get help within 24 hours.

## Volume Discounts

For teams larger than 5 seats, annual billing includes a 15% volume discount. Contact sales@matcraft.ai for custom quotes.

## Trial

New users can start a 14-day free trial of Pro without entering payment information. At the end of the trial, you can choose to subscribe or your account automatically reverts to the free tier with all data preserved.

Question 35

What does the Enterprise plan include?

Accepted Answer

The Enterprise plan is designed for organizations that need advanced security, compliance, dedicated infrastructure, and custom integrations. Pricing is based on your organization's needs -- contact sales@matcraft.ai for a quote.

## Enterprise Features

### Security & Compliance

- **SSO/SAML**: Integrate with your organization's identity provider (Okta, Azure AD, OneLogin, PingFederate). Enforce MFA and session policies through your IdP.
- **Audit logging**: Comprehensive logs of all user actions, API calls, and data access. Exportable in SIEM-compatible formats (CEF, JSON).
- **SOC 2 Type II**: Attestation available upon request under NDA.
- **Data Processing Agreement (DPA)**: Custom DPA with your organization's legal requirements.
- **IP allowlisting**: Restrict API and dashboard access to your corporate network.
- **Custom data residency**: Choose your AWS region for data storage (US, EU, Asia-Pacific).

### Infrastructure

- **Dedicated compute**: Your campaigns run on isolated infrastructure, not shared with other customers. This guarantees consistent performance.
- **GPU allocation**: Dedicated GPU instances for surrogate training with guaranteed availability.
- **Custom scaling**: Configure worker pool sizes, concurrency limits, and priority queues.
- **99.9% SLA**: Uptime guarantee with financial credits for downtime.

### Collaboration

- **Unlimited seats**: No per-seat limits.
- **Organization hierarchy**: Create teams, departments, and projects with nested permissions.
- **Cross-team sharing**: Share materials and campaign templates across teams with controlled access.

### Support

- **Dedicated Slack channel**: Direct access to the MatCraft engineering team.
- **Onboarding assistance**: A solutions engineer helps your team set up their first campaigns and custom domain plugins.
- **Quarterly business reviews**: Regular check-ins to review usage, discuss roadmap, and optimize your workflow.
- **Custom integrations**: We can build connectors to your internal LIMS, ELN, or simulation infrastructure.

### Advanced Features

- **Campaign templates**: Create reusable campaign configurations that enforce organizational standards.
- **Approval workflows**: Require manager approval before running campaigns that exceed cost thresholds.
- **Budget controls**: Set monthly evaluation budgets per team or project.

## Getting Started

Contact sales@matcraft.ai or fill out the form at matcraft.ai/enterprise. Most enterprise deployments are live within 2-4 weeks.

Question 36

Is there an academic discount?

Accepted Answer

Yes. MatCraft offers free Pro-level access to students, faculty, and researchers at accredited academic institutions. We believe cost should not be a barrier to adopting modern materials optimization tools in research.

## Academic Tier Details

The Academic tier includes all Pro plan features at no cost:

- 25 concurrent campaigns
- 25,000 evaluations per month
- Unlimited materials
- Custom domain plugins
- GPU-accelerated surrogate training
- Full API and CLI access

## Eligibility

The Academic tier is available to:

- **Students**: Undergraduate and graduate students enrolled at an accredited university or college. Verification via .edu email address or student ID.
- **Faculty & Researchers**: Professors, postdocs, and research staff at accredited institutions. Verification via institutional email or faculty page link.
- **Research Labs**: Academic research groups can apply for a team Academic license covering up to 20 members.

## How to Apply

1. Sign up for a free MatCraft account.
2. Go to **Settings > Billing > Academic Program**.
3. Enter your institutional email address and department.
4. Upload verification (student ID, faculty page URL, or institutional letter).
5. Applications are typically approved within 1-2 business days.

## Terms

- Academic licenses are valid for 1 year and renewable upon verification of continued affiliation.
- Research performed using MatCraft may be published freely. We only ask that you cite MatCraft in your publications (citation format provided in the dashboard).
- Academic licenses may not be used for commercial product development. If your research transitions to a commercial product, please contact us about a commercial license.
- Data generated under an academic license is yours and can be exported at any time.

## Institutional Agreements

For university-wide deployments or multi-department agreements, we offer institutional licenses with centralized administration. Contact academic@matcraft.io for details.

## Open-Source Alternative

The core MatCraft library is always free and open source, regardless of academic affiliation. The Academic tier specifically covers the managed cloud platform and web dashboard.

Question 37

How does billing work?

Accepted Answer

MatCraft uses a straightforward subscription billing model with no hidden fees or overage charges.

## Billing Cycle

- **Monthly plans**: Billed on the same date each month (e.g., if you subscribe on March 15, you are billed on the 15th of each subsequent month).
- **Annual plans**: Billed once per year at a 17% discount compared to monthly billing ($49/month vs. $59/month for Pro).

## Payment Methods

We accept:

- Credit and debit cards (Visa, Mastercard, American Express)
- ACH bank transfers (US only, annual plans only)
- Wire transfers (Enterprise plans, annual billing)
- Purchase orders (Enterprise plans, contact sales)

All payments are processed securely through Stripe. MatCraft does not store your payment card details.

## Invoices

Invoices are generated automatically at the start of each billing period and available in **Settings > Billing > Invoices**. Each invoice includes:

- Plan name and billing period
- Number of seats
- Subtotal, applicable taxes, and total
- Payment method used

Invoices can be downloaded as PDF for expense reporting.

## Seat Management

- **Adding seats**: You can add team members at any time. The cost for new seats is prorated for the remainder of the current billing period.
- **Removing seats**: Seat reductions take effect at the next billing cycle. The removed member retains access until the end of the current period.

## Usage Tracking

Monitor your evaluation usage in real-time at **Settings > Usage**. The dashboard shows:

- Evaluations used this month vs. your plan limit
- Active campaigns vs. your plan limit
- Usage trends over the past 6 months

## Exceeding Limits

If you hit your monthly evaluation limit:

- Running campaigns pause automatically.
- You can still access the dashboard, view results, and export data.
- You can upgrade your plan immediately to resume campaigns.
- Evaluations do not roll over -- unused evaluations expire at the end of each billing period.

We send email notifications at 75%, 90%, and 100% of your evaluation limit.

## Taxes

Prices displayed are exclusive of tax. Applicable sales tax, VAT, or GST is calculated at checkout based on your billing address.

Question 38

How do I cancel my subscription?

Accepted Answer

You can cancel your MatCraft subscription at any time. There are no cancellation fees or long-term commitments.

## How to Cancel

1. Log in to your MatCraft dashboard.
2. Go to **Settings > Billing**.
3. Click **Cancel Subscription**.
4. Select a reason (optional, helps us improve).
5. Confirm the cancellation.

## What Happens After Cancellation

- **Immediate**: Your cancellation is confirmed via email.
- **Until end of billing period**: You retain full access to all Pro/Enterprise features for the remainder of your current billing period. If you cancel on day 10 of a monthly cycle, you have access for the remaining 20 days.
- **After billing period ends**: Your account automatically downgrades to the Free tier.

## Your Data

**Your data is never deleted upon cancellation.** Specifically:

- All materials, campaigns, results, and exported data remain accessible.
- If you exceed Free tier limits (e.g., more than 3 active campaigns), excess campaigns are paused but not deleted. You can resume them by upgrading again or archiving campaigns to bring your count under the limit.
- Campaign history and results are retained for 12 months of inactivity on the Free tier.

## Re-Subscribing

If you decide to come back, simply go to **Settings > Billing** and choose a plan. All your existing data, campaigns, and configurations will be available immediately. There is no re-onboarding process.

## Annual Plan Cancellation

For annual plans:

- You can cancel at any time, but no prorated refund is issued for the remaining months.
- You retain access through the end of the annual billing period.
- If you are within 30 days of your annual renewal, contact support@matcraft.io to cancel before the next charge.

## Enterprise Cancellation

Enterprise plans have a 30-day notice period specified in your contract. Contact your account manager or email sales@matcraft.ai to initiate cancellation. We will work with you on data export and transition planning.

## Exporting Before Cancellation

We recommend exporting your data before cancellation:

```bash
materia data export --all --format parquet --output ./matcraft-backup/
```

Question 39

How do I set up team accounts?

Accepted Answer

MatCraft supports collaborative team workflows on Pro and Enterprise plans. Here is how to set up and manage your team.

## Creating a Team

1. Go to **Settings > Team**.
2. Click **Create Team** and enter a team name (e.g., "Membrane Research Group").
3. Your account becomes the Team Owner with full administrative privileges.

## Inviting Members

Invite team members by email:

1. Go to **Settings > Team > Members**.
2. Click **Invite Member**.
3. Enter their email address and assign a role.
4. They will receive an invitation email with a link to join.

If the invitee does not have a MatCraft account, they can create one as part of accepting the invitation.

## Roles and Permissions

| Permission | Viewer | Editor | Admin | Owner |
|-----------|--------|--------|-------|-------|
| View campaigns & results | Yes | Yes | Yes | Yes |
| Export data | Yes | Yes | Yes | Yes |
| Create/edit materials | No | Yes | Yes | Yes |
| Run campaigns | No | Yes | Yes | Yes |
| Import data | No | Yes | Yes | Yes |
| Invite members | No | No | Yes | Yes |
| Manage roles | No | No | Yes | Yes |
| Billing & plan changes | No | No | No | Yes |
| Delete team | No | No | No | Yes |

## Shared Resources

Team members share the following resources under the team's plan limits:

- **Campaigns**: All team members can see campaigns created by any team member (unless marked private).
- **Materials**: Material definitions are shared across the team.
- **Evaluation budget**: The monthly evaluation limit is pooled across all team members.

## Campaign Permissions

Individual campaigns can be restricted:

```
Campaign "cathode-study-v3"
├── Owner: alice@lab.edu (full control)
├── Editor: bob@lab.edu (can add data, run iterations)
└── Viewer: carol@lab.edu (can view results only)
```

## API Access

Each team member generates their own API token. Tokens inherit the member's role permissions. For CI/CD pipelines, create a dedicated service account:

1. Go to **Settings > Team > Service Accounts**.
2. Click **Create Service Account**.
3. Assign it a name (e.g., "CI Pipeline") and role (typically Editor).
4. Generate and securely store its API token.

## Team Billing

All seats are billed to the Team Owner's payment method. The cost is $49/seat/month (annual) or $59/seat/month (monthly). Viewers count as seats. Service accounts do not count as seats.

Question 40

What are the API rate limits?

Accepted Answer

MatCraft applies rate limits to the REST API to ensure fair usage and platform stability. Limits vary by plan.

## Rate Limits by Plan

| Plan | Requests per minute | Requests per hour | Concurrent campaigns |
|------|--------------------|--------------------|---------------------|
| Free | 60 | 1,000 | 3 |
| Pro | 300 | 10,000 | 25 |
| Enterprise | Custom (default: 1,000) | Custom (default: 50,000) | Unlimited |

## How Rate Limits Work

Rate limits are applied per API token (not per IP address). When you exceed a limit, the API returns a `429 Too Many Requests` response with headers indicating when you can retry:

```
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1680000060
Retry-After: 45
```

## Rate Limit Headers

Every API response includes rate limit information:

```
X-RateLimit-Limit: 300          # Your plan's per-minute limit
X-RateLimit-Remaining: 247      # Requests remaining in current window
X-RateLimit-Reset: 1680000060   # Unix timestamp when the window resets
```

## SDK Handling

The Python SDK automatically handles rate limiting with exponential backoff:

```python
from materia import Client

client = Client(
    base_url="https://api.matcraft.ai/api/v1",
    token="mc_live_abc123...",
    max_retries=3,           # Retry up to 3 times on 429
    retry_backoff_factor=2,  # Wait 2, 4, 8 seconds between retries
)
```

## Endpoint-Specific Limits

Some endpoints have additional limits to prevent abuse:

| Endpoint | Additional Limit |
|----------|-----------------|
| `POST /v1/campaigns` | 10 per hour (Free), 50 per hour (Pro) |
| `POST /v1/data/import` | 100 MB per request |
| `GET /v1/campaigns/:id/stream` | 5 concurrent WebSocket connections |
| `POST /v1/evaluate` | Counted against monthly evaluation limit |

## Batch API

For bulk operations, use the batch API endpoint which counts as a single request regardless of the number of items:

```bash
curl -X POST https://api.matcraft.ai/api/v1/batch \
  -H "Authorization: Bearer $MATCRAFT_TOKEN" \
  -d '{
    "requests": [
      {"method": "GET", "path": "/v1/materials/mat-001"},
      {"method": "GET", "path": "/v1/materials/mat-002"},
      {"method": "GET", "path": "/v1/campaigns?material_id=mat-001"}
    ]
  }'
```

## Requesting Higher Limits

If your workflow requires higher rate limits, contact support@matcraft.io with your use case. Enterprise customers can configure custom limits as part of their contract.

Question 41

What is MatCraft's system architecture?

Accepted Answer

MatCraft follows a modern, layered architecture with clear separation between the frontend, backend API, task processing, and core optimization engine.

## Architecture Overview

```
┌──────────────────┐     ┌──────────────────┐
│   Next.js        │     │   Python SDK /   │
│   Frontend       │     │   CLI            │
│   (Port 3000)    │     │                  │
└────────┬─────────┘     └────────┬─────────┘
         │                        │
         │  REST / WebSocket      │  REST
         │                        │
         ▼                        ▼
┌──────────────────────────────────────────┐
│          FastAPI Backend (Port 8000)      │
│  ┌────────┐ ┌────────┐ ┌──────────────┐ │
│  │ Routes │ │ Auth   │ │ WebSocket    │ │
│  │        │ │ (JWT)  │ │ Manager      │ │
│  └────────┘ └────────┘ └──────────────┘ │
└────────────────┬─────────────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
┌──────────────┐  ┌──────────────┐
│  PostgreSQL  │  │    Redis     │
│  (Data)      │  │  (Queue +    │
│              │  │   Pub/Sub)   │
└──────────────┘  └──────┬───────┘
                         │
                         ▼
                 ┌──────────────┐
                 │   Celery     │
                 │   Workers    │
                 │  ┌────────┐  │
                 │  │materia │  │
                 │  │ core   │  │
                 │  └────────┘  │
                 └──────────────┘
```

## Component Details

### Frontend (Next.js 14)

- **Framework**: Next.js with App Router and React Server Components.
- **Styling**: Tailwind CSS with shadcn/ui component library.
- **State management**: Zustand for client state, React Query for server state.
- **Real-time**: WebSocket connection for live campaign progress updates.
- **Visualization**: Recharts for convergence plots, Plotly.js for interactive 3D Pareto surfaces.

### Backend (FastAPI)

- **Framework**: FastAPI with async request handling.
- **Authentication**: JWT tokens with refresh rotation. OAuth2 support for GitHub/Google.
- **Database ORM**: SQLAlchemy 2.0 with async session management.
- **API documentation**: Auto-generated OpenAPI/Swagger at `/docs`.
- **WebSocket**: Real-time campaign updates pushed to connected clients.

### Task Queue (Celery + Redis)

- **Broker**: Redis serves as both the message broker and result backend.
- **Workers**: Celery workers execute long-running tasks: surrogate training, CMA-ES optimization, and active learning iterations.
- **Concurrency**: Each worker runs multiple threads/processes depending on whether the task is CPU-bound (optimization) or I/O-bound (data import).

### Core Library (materia)

- **Location**: `src/materia/`
- **Pure Python**: No web framework dependencies. Can be used standalone.
- **Key modules**: `surrogate/` (MLP, ONNX), `optimize/` (CMA-ES), `active_learning/` (acquisition functions, convergence), `analysis/` (Pareto computation), `plugins/` (domain definitions).

### Database (PostgreSQL)

- **Schema**: Normalized schema with tables for organizations, users, materials, campaigns, iterations, candidates, and measurements.
- **Migrations**: Managed with Alembic. Run `materia db upgrade` to apply.

This architecture ensures that the compute-intensive optimization runs asynchronously without blocking the API, while the frontend receives real-time updates via WebSocket.

Question 42

What are the database requirements?

Accepted Answer

MatCraft uses PostgreSQL as its primary data store. Here are the requirements, configuration recommendations, and scaling considerations.

## Minimum Requirements

| Requirement | Minimum | Recommended |
|-------------|---------|-------------|
| PostgreSQL version | 14 | 16 |
| Storage | 1 GB | 10 GB+ |
| RAM | 256 MB (shared) | 1 GB+ dedicated |
| Connections | 20 | 100+ |

## Local Development

For local development, the simplest setup is Docker:

```bash
docker run -d \
  --name matcraft-db \
  -e POSTGRES_DB=matcraft \
  -e POSTGRES_USER=matcraft \
  -e POSTGRES_PASSWORD=matcraft \
  -p 5432:5432 \
  -v matcraft-pgdata:/var/lib/postgresql/data \
  postgres:16-alpine
```

Alternatively, the core library can use **SQLite** for single-user, local-only usage (no web dashboard):

```bash
# SQLite mode (core library only, no server)
export MATCRAFT_DATABASE_URL="sqlite:///./matcraft.db"
materia campaign run --config my_material.yaml
```

## Connection String

Configure the database URL in your `.env` file:

```
DATABASE_URL=postgresql://user:password@host:5432/matcraft
```

For connection pooling in production, use PgBouncer or your cloud provider's built-in connection pooler:

```
DATABASE_URL=postgresql://user:password@pgbouncer:6432/matcraft?pgbouncer=true
```

## Schema Management

MatCraft uses Alembic for database migrations:

```bash
# Apply all pending migrations
materia db upgrade

# Check current migration version
materia db current

# Generate a new migration after model changes (development)
materia db revision --autogenerate -m "add campaign tags"
```

## Key Tables

| Table | Purpose | Growth Rate |
|-------|---------|-------------|
| `materials` | Material definitions | Slow (10s-100s) |
| `campaigns` | Campaign metadata | Slow (10s-100s) |
| `iterations` | Per-iteration state | Moderate (100s-1000s) |
| `candidates` | Proposed compositions | Fast (1000s-10000s) |
| `measurements` | Evaluation results | Fast (1000s-10000s) |
| `surrogate_checkpoints` | Serialized model weights | Moderate (MBs per checkpoint) |

## Production Recommendations

- **Backups**: Enable automated daily backups with point-in-time recovery. For AWS RDS, this is enabled by default.
- **Monitoring**: Track connection pool usage, query latency (p95), and disk usage. Alert when connections exceed 80% of the pool or disk usage exceeds 80%.
- **Indexing**: MatCraft creates necessary indexes during migration. For very large deployments (>100k candidates), consider adding partial indexes on the `candidates` table for active campaigns.
- **Vacuuming**: Ensure autovacuum is enabled (it is by default in PostgreSQL). The `candidates` table sees frequent inserts and benefits from regular vacuuming.

## Managed Database Services

Tested and recommended managed PostgreSQL services:

- **AWS RDS**: Use `db.t3.medium` for small teams, `db.r6g.large` for production.
- **Google Cloud SQL**: Standard tier with 1+ vCPU.
- **Azure Database for PostgreSQL**: Flexible Server, General Purpose tier.
- **Supabase**: Works well for small deployments.

Question 43

How does real-time campaign monitoring work?

Accepted Answer

MatCraft uses WebSocket connections to push real-time updates from running campaigns to the dashboard and connected clients. This eliminates the need for polling and provides an instant, reactive experience.

## How It Works

1. When you open a campaign page in the dashboard, the frontend establishes a WebSocket connection to the backend at `/ws/campaigns/{campaign_id}`.
2. The backend subscribes to a Redis Pub/Sub channel for that campaign.
3. As the Celery worker progresses through optimization iterations, it publishes events to the Redis channel.
4. The backend forwards these events to all connected WebSocket clients.

## Event Types

```typescript
type CampaignEvent =
  | { type: "iteration_started"; iteration: number; timestamp: string }
  | { type: "surrogate_trained"; metrics: { train_loss: number; val_loss: number } }
  | { type: "candidates_proposed"; candidates: Candidate[]; iteration: number }
  | { type: "candidates_evaluated"; results: EvaluationResult[]; iteration: number }
  | { type: "iteration_completed"; iteration: number; best_value: number; pareto_size: number }
  | { type: "campaign_completed"; total_iterations: number; total_evaluations: number }
  | { type: "campaign_error"; error: string; iteration: number }
  | { type: "convergence_update"; metric: number; converged: boolean };
```

## Frontend Integration

The dashboard uses these events to update visualizations in real-time:

- **Convergence plot**: New data points appear as each iteration completes.
- **Pareto plot**: The Pareto front is redrawn as new candidates are evaluated.
- **Candidate table**: New candidates appear with their predicted and (once evaluated) actual objective values.
- **Progress indicator**: Shows the current iteration, elapsed time, and estimated time remaining.

## Python SDK Streaming

You can also stream events in the Python SDK:

```python
from materia import Client

client = Client(base_url="https://api.matcraft.ai/api/v1", token="mc_live_...")

for event in client.campaigns.stream("camp-123"):
    if event.type == "iteration_completed":
        print(f"Iteration {event.iteration}: best = {event.best_value:.4f}")
    elif event.type == "campaign_completed":
        print(f"Done! {event.total_iterations} iterations, {event.total_evaluations} evaluations")
        break
```

## CLI Live Output

The CLI shows real-time progress when running a campaign:

```
$ materia campaign run --config my_material.yaml
[Iter  1/20] Training surrogate... done (0.8s, val_loss=0.0342)
[Iter  1/20] Optimizing acquisition... done (1.2s, 5 candidates)
[Iter  1/20] Evaluating candidates... done (0.3s)
[Iter  1/20] Best: water_flux=42.3, salt_rejection=93.1%
[Iter  2/20] Training surrogate... done (0.9s, val_loss=0.0215)
...
```

## Scaling WebSockets

For high-concurrency deployments with many simultaneous dashboard users:

- The FastAPI backend uses async WebSocket handlers, supporting thousands of concurrent connections per process.
- Redis Pub/Sub handles cross-process message distribution when running multiple API server instances behind a load balancer.
- WebSocket connections are authenticated with the same JWT token used for REST API calls.

Question 44

How does the Celery task queue work?

Accepted Answer

MatCraft uses Celery with Redis as the message broker to run optimization tasks asynchronously. This architecture keeps the API responsive while computationally intensive surrogate training and optimization run in the background. ## Why Celery? Materials optimization involves CPU-intensive tasks that can take seconds to minutes per iteration: - **Surrogate training**: Training an MLP on hundreds to thousands of data points (1-30 seconds depending on architecture and dataset size). - **CMA-ES optimization**: Running hundreds of generations to optimize the acquisition function (1-10 seconds). - **Evaluation**: Running physics models or external simulations (seconds to hours). Running these in the API request-response cycle would cause timeouts. Celery offloads them to dedicated worker processes. ## Task Flow ``` API Server Redis Celery Worker │ │ │ │ POST /campaigns/run │ │ │──────────────────────────>│ │ │ task_id = "abc-123" │ │ │<──────────────────────────│ │ │ │ pick up task │ │ │──────────────────────────>│ │ │ │ Train surrogate │ │ publish progress event │ │ │<──────────────────────────│ │ WebSocket push to client │ │ │<──────────────────────────│ │ │ │ │ Run CMA-ES │ │ publish progress event │ │ │<──────────────────────────│ │ WebSocket push to client │ │ │<──────────────────────────│ │ │ │ task complete │ │ │<──────────────────────────│ ``` ## Configuration Worker configuration in your `.env` or Celery config: ```python # celery_config.py broker_url = "redis://localhost:6379/0" result_backend = "redis://localhost:6379/1" task_serializer = "json" result_serializer = "json" accept_content = ["json"] task_time_limit = 3600 # Hard limit: 1 hour per task task_soft_time_limit = 3000 # Soft limit: 50 minutes (raises exception) worker_prefetch_multiplier = 1 # One task at a time per worker process worker_concurrency = 4 # 4 parallel worker processes ``` ## Running Workers ```bash # Single worker with 4 processes celery -A materia.tasks worker --loglevel=info --concurrency=4 # GPU worker for surrogate training (single process, GPU-bound) celery -A materia.tasks worker --loglevel=info --concurrency=1 \ --queues=gpu_training -n gpu-worker@%h # Priority queues celery -A materia.tasks worker --loglevel=info \ --queues=high_priority,default,low_priority ``` ## Task Types | Task | Queue | Typical Duration | Priority | |------|-------|-----------------|----------| | `train_surrogate` | default (or gpu_training) | 1-30s | High | | `run_cmaes_optimization` | default | 1-10s | High | | `evaluate_candidates` | default | 0.1s - 1h | Medium | | `compute_pareto_front` | default | 0.1-5s | Low | | `export_results` | low_priority | 1-60s | Low | | `cleanup_old_checkpoints` | low_priority | 1-10s | Low | ## Monitoring Use Flower for a web-based Celery monitoring dashboard: ```bash pip install flower celery -A materia.tasks flower --port=5555 ``` This provides real-time visibility into task queues, worker status, task history, and performance metrics at `http://localhost:5555`. ## Scaling Workers Add more workers to handle higher campaign throughput: ```bash # Run 3 worker instances docker compose up -d --scale worker=3 ``` Each worker independently pulls tasks from Redis, so scaling is straightforward. The only shared state is the PostgreSQL database.

Question 45

What are the best practices for cloud deployment?

Accepted Answer

Deploying MatCraft to production requires attention to security, reliability, and performance. Here is a comprehensive guide covering the most important considerations. ## Infrastructure Sizing ### Small Team (1-5 users, <10 concurrent campaigns) | Component | Specification | |-----------|--------------| | API Server | 1 instance, 2 vCPU, 4 GB RAM | | Workers | 2 instances, 2 vCPU, 4 GB RAM each | | Database | Managed PostgreSQL, 2 vCPU, 4 GB RAM, 50 GB storage | | Redis | Managed Redis, 1 GB RAM | | Estimated cost | $200-400/month (AWS) | ### Medium Team (5-20 users, 10-50 concurrent campaigns) | Component | Specification | |-----------|--------------| | API Server | 2 instances behind ALB, 2 vCPU, 8 GB RAM each | | Workers | 4-8 instances, 4 vCPU, 8 GB RAM each | | Database | Managed PostgreSQL, 4 vCPU, 16 GB RAM, 200 GB storage, read replica | | Redis | Managed Redis, 2 GB RAM, cluster mode | | Estimated cost | $800-1,500/month (AWS) | ## Security Checklist - [ ] **TLS everywhere**: Use ACM (AWS) or Let's Encrypt for TLS certificates. Enforce HTTPS redirection. - [ ] **Strong secrets**: Generate a cryptographically random `SECRET_KEY` (at least 32 bytes). Never reuse across environments. - [ ] **Database credentials**: Store in AWS Secrets Manager, not environment variables or config files. - [ ] **Network isolation**: Place the database and Redis in a private subnet. Only the API server should have direct access. - [ ] **WAF**: Enable AWS WAF or Cloudflare in front of the API to block common attacks. - [ ] **CORS**: Configure allowed origins to match your frontend domain only. - [ ] **Rate limiting**: The API has built-in rate limiting, but consider adding an external rate limiter at the load balancer level for DDoS protection. ## Environment Variables ```bash # Required DATABASE_URL=postgresql://user:pass@rds-endpoint:5432/matcraft REDIS_URL=redis://elasticache-endpoint:6379/0 SECRET_KEY= MATCRAFT_ENV=production # Optional CORS_ORIGINS=https://matcraft.yourcompany.com LOG_LEVEL=info SENTRY_DSN=https://abc@sentry.io/123 # Error tracking ``` ## Health Checks Configure your load balancer to check these endpoints: - **API**: `GET /health` -- returns 200 if the API is running and the database is reachable. - **Worker**: Celery workers report health via the `celery inspect ping` command. Set up a sidecar that exposes this as an HTTP endpoint. ## Backup Strategy - **Database**: Automated daily snapshots with 7-day retention. Enable point-in-time recovery (PITR) for granular restoration. - **Redis**: Redis data is ephemeral (task queue). No backups needed -- tasks will be re-queued if Redis restarts. - **Surrogate checkpoints**: Stored in the database. Covered by database backups. ## Monitoring and Alerting Set up alerts for: | Metric | Warning Threshold | Critical Threshold | |--------|-------------------|--------------------| | API error rate (5xx) | >1% | >5% | | API latency (p95) | >500ms | >2000ms | | Worker queue depth | >50 tasks | >200 tasks | | Database connections | >80% pool | >95% pool | | Database disk usage | >70% | >85% | | Redis memory | >70% | >85% | Use CloudWatch (AWS), Prometheus + Grafana (self-managed), or Datadog for monitoring.

Question 46

How do I scale MatCraft for large workloads?

Accepted Answer

MatCraft is designed to scale horizontally. Here is how to handle increasing numbers of users, campaigns, and evaluations.

## Scaling the API Layer

The FastAPI backend is stateless -- all session state is stored in the database and Redis. To handle more concurrent users:

```bash
# Scale API instances behind a load balancer
docker compose up -d --scale api=4
```

Each API instance can handle approximately 500 concurrent connections (including WebSocket). For 100 concurrent dashboard users, 2-3 instances are sufficient.

**Key considerations:**

- Use sticky sessions (session affinity) at the load balancer for WebSocket connections.
- All instances share the same database and Redis, so no state synchronization is needed.

## Scaling Workers

Workers are the primary bottleneck for campaign throughput. Each worker process handles one task at a time:

```bash
# Scale horizontally (more worker containers)
docker compose up -d --scale worker=8

# Scale vertically (more processes per worker)
celery -A materia.tasks worker --concurrency=8
```

**Rules of thumb:**

- Each campaign iteration requires 1 worker process for 2-30 seconds.
- For N concurrent campaigns running simultaneously, you need approximately N/2 worker processes (since campaigns spend time waiting between iterations).
- CPU-bound tasks (CMA-ES, surrogate training): Set concurrency equal to the number of CPU cores.
- GPU-bound tasks (large surrogate training): Set concurrency to 1 per GPU.

## Priority Queues

For mixed workloads, use priority queues to ensure interactive requests are not blocked by batch jobs:

```python
# In task definitions
@app.task(queue="high_priority")
def train_surrogate(campaign_id: str):
    ...

@app.task(queue="low_priority")
def export_results(campaign_id: str):
    ...
```

```bash
# Dedicated workers per queue
celery -A materia.tasks worker --queues=high_priority --concurrency=4
celery -A materia.tasks worker --queues=low_priority --concurrency=2
```

## Scaling the Database

PostgreSQL is typically the last bottleneck. Strategies for scaling:

1. **Connection pooling**: Use PgBouncer between the application and PostgreSQL. This reduces the number of direct database connections from (API instances * worker processes * connections per process) to a manageable pool.

2. **Read replicas**: Route read-heavy dashboard queries (listing campaigns, viewing results) to a read replica. Write operations (creating candidates, storing measurements) go to the primary.

3. **Partitioning**: For very large deployments (>1M candidates), partition the `candidates` table by campaign ID:

```sql
CREATE TABLE candidates (
    id UUID PRIMARY KEY,
    campaign_id UUID NOT NULL,
    ...
) PARTITION BY HASH (campaign_id);
```

## Auto-Scaling

On Kubernetes or ECS, configure horizontal pod auto-scaling based on:

- **API pods**: Scale on CPU utilization (target: 60%) or request rate.
- **Worker pods**: Scale on Redis queue depth (target: <10 pending tasks per worker).

```yaml
# Kubernetes HPA example
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: matcraft-worker
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: matcraft-worker
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: External
      external:
        metric:
          name: redis_queue_depth
        target:
          type: AverageValue
          averageValue: "10"
```

Question 47

Does MatCraft support GPU acceleration?

Accepted Answer

Yes. MatCraft supports GPU acceleration for surrogate model training, which can provide a 5-20x speedup for large datasets and complex model architectures.

## When GPU Helps

GPU acceleration is most beneficial when:

- **Large datasets**: More than 1,000 training points. For smaller datasets, the overhead of moving data to GPU memory outweighs the computation benefit.
- **Large models**: Hidden layers with 256+ neurons or 3+ layers. Small models (64-64) train fast enough on CPU.
- **Frequent retraining**: Active learning campaigns retrain the surrogate every iteration. Faster training means faster campaign completion.
- **Ensemble surrogates**: Training 5-10 independent models benefits significantly from GPU parallelism.

## Installation

Install the GPU-enabled version:

```bash
pip install matcraft[gpu]
```

This installs PyTorch with CUDA support. Verify GPU availability:

```python
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"GPU: {torch.cuda.get_device_name(0)}")
```

## Configuration

Enable GPU training in your campaign config:

```yaml
surrogate:
  type: mlp
  device: cuda        # "cpu" or "cuda" (default: auto-detect)
  hidden_layers: [256, 256, 128]
  epochs: 500
  batch_size: 256     # Larger batch sizes benefit more from GPU
```

Or in Python:

```python
from materia.surrogate import MLPSurrogate

surrogate = MLPSurrogate(
    hidden_layers=[256, 256, 128],
    device="cuda",
    batch_size=256,
)
```

## Docker with GPU

Use the NVIDIA Container Toolkit:

```bash
# Install NVIDIA Container Toolkit
# (See: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)

# Run with GPU support
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
```

The GPU compose override:

```yaml
# docker-compose.gpu.yml
services:
  worker:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      MATCRAFT_DEVICE: cuda
```

## Supported GPUs

| GPU | Status | Notes |
|-----|--------|-------|
| NVIDIA A100 | Fully supported | Best performance, recommended for production |
| NVIDIA V100 | Fully supported | Good performance |
| NVIDIA T4 | Fully supported | Cost-effective for cloud (AWS g4dn instances) |
| NVIDIA RTX 3090/4090 | Supported | Good for local development |
| NVIDIA RTX 3060/4060 | Supported | Adequate for small to medium models |
| AMD GPUs (ROCm) | Experimental | Requires PyTorch ROCm build |
| Apple M1/M2/M3 (MPS) | Experimental | Use `device: mps` |

## Performance Benchmarks

Training time for an MLP surrogate with `[256, 256, 128]` architecture, 200 epochs:

| Dataset Size | CPU (i7-12700) | GPU (RTX 3090) | Speedup |
|-------------|----------------|----------------|---------|
| 100 points | 2.1s | 1.8s | 1.2x |
| 1,000 points | 8.3s | 1.9s | 4.4x |
| 10,000 points | 45.2s | 3.1s | 14.6x |
| 100,000 points | 412s | 21.4s | 19.3x |

For typical active learning campaigns with <1,000 data points, CPU training is fast enough. GPU becomes valuable for large-scale campaigns or when running many campaigns concurrently.

## Cloud GPU Instances

Recommended cloud instances for GPU workers:

- **AWS**: `g4dn.xlarge` (T4, $0.52/hr) for cost-effective training
- **GCP**: `n1-standard-4` with T4 ($0.35/hr + $0.35/hr GPU)
- **Azure**: `Standard_NC4as_T4_v3` (T4, $0.53/hr)

Question 48

How can I contribute to MatCraft?

Accepted Answer

We welcome contributions to the MatCraft open-source core. Whether you are fixing a bug, adding a domain plugin, improving documentation, or implementing a new feature, here is how to get started. ## Getting Set Up ```bash # Fork and clone the repository git clone https://github.com/YOUR_USERNAME/matcraft.git cd matcraft # Create a virtual environment python -m venv .venv source .venv/bin/activate # Install in development mode with all extras pip install -e ".[dev,test,docs]" # Install pre-commit hooks pre-commit install # Verify everything works pytest ``` ## Development Workflow 1. **Create a branch** from `main`: ```bash git checkout -b feature/my-new-feature ``` 2. **Make your changes** with tests. We maintain >90% test coverage. 3. **Run the test suite**: ```bash # Run all tests pytest # Run specific test file pytest tests/test_surrogate_mlp.py # Run with coverage pytest --cov=materia --cov-report=html ``` 4. **Run linting and formatting**: ```bash # These run automatically via pre-commit hooks ruff check src/ tests/ ruff format src/ tests/ mypy src/materia/ ``` 5. **Submit a pull request** against `main` with a clear description of your changes. ## Contribution Areas ### Domain Plugins (Most Welcome) Adding new material domain plugins is one of the most impactful contributions. A domain plugin consists of: - A `components.yaml` file defining the parameter schema - A `physics.py` file with approximate evaluation models - Tests in `tests/test_plugin_.py` - Documentation in `docs/domains/.md` See `src/materia/plugins/water/` for a complete example. ### Surrogate Models We are interested in alternative surrogate architectures: - Gaussian Process surrogates - Graph Neural Network surrogates (for crystal structures) - Ensemble methods - Transfer learning across domains ### Optimization Algorithms Beyond CMA-ES, we would welcome implementations of: - Differential Evolution - Particle Swarm Optimization - Multi-objective evolutionary algorithms (NSGA-II, MOEA/D) ### Bug Fixes and Improvements Check the [GitHub Issues](https://github.com/matcraft/matcraft/issues) page for open bugs and feature requests labeled `good-first-issue` or `help-wanted`. ## Code Style - Python code follows PEP 8, enforced by Ruff. - Type hints are required for all public APIs. - Docstrings follow the NumPy style. - Tests use pytest with fixtures defined in `conftest.py`. ## Contributor License Agreement All contributors must sign a CLA before their first pull request can be merged. The CLA bot will automatically comment on your PR with instructions. The CLA allows us to distribute your contributions under the Apache 2.0 license. ## Recognition All contributors are listed in the CONTRIBUTORS.md file and acknowledged in release notes. Significant contributors may be invited to join the core maintainer team.

Question 49

What data sources does MatCraft use?

Accepted Answer

MatCraft aggregates materials data from three major open databases:

## Materials Project (MP)

The largest source in MatCraft, providing ~150,000 materials computed with DFT using the PBE functional with Hubbard U corrections for transition metals. MP data includes crystal structures, formation energies, band gaps, elastic properties, and electronic structure (band structure and DOS).

## AFLOW

The Automatic FLOW repository contributes ~60,000 additional materials. AFLOW uses similar DFT methods (PBE) but with different pseudopotentials and convergence settings. AFLOW provides thermodynamic, electronic, and mechanical properties.

## JARVIS-DFT

The Joint Automated Repository for Various Integrated Simulations adds ~40,000 materials computed with the OptB88vdW functional, which better captures van der Waals interactions. JARVIS data includes band gaps (both OPT and MBJ functionals), elastic constants, and solar efficiency estimates.

Each material in MatCraft is tagged with its source so you can filter by database when comparing properties.

Question 50

How often is the materials data updated?

Accepted Answer

MatCraft refreshes its database on a quarterly basis, synchronizing with the latest releases from each data source:

- **Materials Project**: Updated when MP releases new database versions (approximately every 3-6 months)
- **AFLOW**: Updated when new AFLOW releases are published
- **JARVIS**: Updated with each new JARVIS-DFT release

The "last updated" date is shown on each material's detail page. You can also check the database version on the About page.

For the most current data, you can always query the upstream databases directly. MatCraft provides links to the original source page for each material.

Question 51

How accurate are the computed material properties?

Accepted Answer

The accuracy depends on the property and the computational method used:

## Band Gaps

DFT band gaps calculated with GGA (PBE) functionals systematically underestimate experimental values by 30-50%. For example, silicon's computed gap is typically 0.6 eV vs. the experimental 1.12 eV. JARVIS provides MBJ-corrected band gaps that are more accurate for many materials.

## Formation Energies

GGA formation energies are generally accurate to within 0.1-0.2 eV/atom for most inorganic compounds. The Materials Project applies energy corrections for certain elements (O, S, N) and oxidation states.

## Energy Above Hull (Ehull)

This is a relative quantity and benefits from error cancellation. Ehull values < 0.025 eV/atom reliably indicate thermodynamically stable phases. The error in Ehull is typically 0.02-0.05 eV/atom.

## Crystal Structures

Computed lattice parameters are typically within 1-3% of experimental values for GGA calculations. Interatomic distances are reliable for most bonding environments.

## General Advice

Use computed properties for screening and trend identification rather than precise quantitative predictions. Always validate top candidates with higher-level calculations (HSE06, GW) or experimental measurements.

Question 52

Are there duplicate materials across databases?

Accepted Answer

Yes, many materials appear in multiple databases (MP, AFLOW, JARVIS) since they compute overlapping sets of structures. MatCraft does not deduplicate these entries because:

1. **Different methods**: Each database uses different DFT settings (functionals, pseudopotentials, convergence criteria), so property values differ
2. **Useful for comparison**: Seeing the same material from multiple sources lets you assess the sensitivity of computed properties to methodology
3. **Different properties**: Some properties are only available from specific databases

When searching, you can filter by data source to see results from a single database. The material detail page shows the data source badge and links to the original database entry.

Question 53

Why are some properties missing for certain materials?

Accepted Answer

Not all properties are computed for every material in the database. Common reasons:

- **Band structure / DOS**: Only available for materials with electronic structure calculations in Materials Project. AFLOW and JARVIS materials may not have these.
- **Elastic properties**: Require separate elastic constant calculations that have not been performed for all materials.
- **Band gap = 0**: Metals have zero band gap by definition; this is a real value, not missing data.
- **Phase diagrams**: Require all competing phases in the chemical system to be computed, which may not be complete for exotic element combinations.

Missing values are displayed as "--" or "N/A" in the interface. In the API, missing fields are either absent from the JSON response or set to null.

Question 54

Can I upload my own materials data to MatCraft?

Accepted Answer

Currently, MatCraft serves as a read-only aggregator of public materials databases. You cannot upload custom materials to the shared database.

However, for the optimization campaign workflow, you can:

1. **Import seed data**: Upload CSV or JSON files with your experimental measurements as starting data for optimization campaigns
2. **Custom evaluations**: Use the Python SDK to wrap your own simulation codes or experimental workflows as evaluation backends

For self-hosted deployments, you have full control over the database and can add custom materials to your local instance.

We are exploring a community contribution feature for a future release that would allow vetted users to submit validated data.

Question 55

What are the licensing terms for the materials data?

Accepted Answer

Each data source has its own license:

- **Materials Project**: Creative Commons Attribution 4.0 (CC BY 4.0). You may use, share, and adapt the data with proper attribution.
- **AFLOW**: Available under a permissive academic license. See aflowlib.org for terms.
- **JARVIS**: Public domain, distributed by NIST. No restrictions on use.

MatCraft aggregates and presents this data but does not claim ownership. When using data from MatCraft in publications, please cite both MatCraft and the original data source(s). Citation information is provided on each material's detail page.

Question 56

How many materials are in the MatCraft database?

Accepted Answer

MatCraft currently contains over 205,000 materials:

- **Materials Project**: ~150,000 materials
- **AFLOW**: ~60,000 materials (some overlap with MP)
- **JARVIS-DFT**: ~40,000 materials (some overlap with MP)

The total unique chemical compositions number approximately 180,000 after accounting for cross-database overlap. The database grows with each quarterly update as the upstream sources add new calculations.

You can see the current count and breakdown on the MatCraft dashboard.

Question 57

Does MatCraft include experimental data?

Accepted Answer

MatCraft primarily contains computationally predicted (DFT) properties, not experimental measurements. This is because:

1. Computational data is systematic and covers a much larger chemical space
2. DFT calculations provide a consistent set of properties for every material
3. Experimental data is scattered across literature and difficult to aggregate uniformly

However, some experimental context is available:

- ICSD (Inorganic Crystal Structure Database) structures are used as starting points for many DFT calculations
- The Materials Project validates key materials against experimental data
- JARVIS includes comparison with available experimental band gaps

For experimental properties, we recommend complementary databases like the NIST Materials Data Repository, Springer Materials, or Citrine Informatics.

Question 58

How should I cite MatCraft data in publications?

Accepted Answer

When using MatCraft data in academic publications, please cite both MatCraft and the original data source(s).

## Citing MatCraft

Include the MatCraft URL and access date:

> Materials data retrieved from MatCraft (https://matcraft.ai), accessed [date].

## Citing Original Sources

Each material's detail page shows which database it comes from. Cite the appropriate source:

- **Materials Project**: A. Jain et al., "Commentary: The Materials Project: A materials genome approach to accelerating materials innovation," APL Materials 1, 011002 (2013).
- **AFLOW**: S. Curtarolo et al., "AFLOW: An automatic framework for high-throughput materials discovery," Computational Materials Science 58, 218-226 (2012).
- **JARVIS-DFT**: K. Choudhary et al., "The joint automated repository for various integrated simulations (JARVIS) for data-driven materials design," npj Computational Materials 6, 173 (2020).

## Per-Material Citation

Click the "Cite" button on any material detail page to copy a formatted citation that includes the material ID, data source, and access date.

Question 59

What is band gap and why does it matter?

Accepted Answer

The band gap is the energy difference (in electron volts, eV) between the highest occupied electronic state and the lowest unoccupied state in a solid material.

## Why It Matters

The band gap determines a material's fundamental electronic behavior:

- **Zero band gap (metals)**: Electrons flow freely, making the material a conductor (e.g., copper, iron)
- **Small band gap (0.1-1.5 eV)**: Semiconductor behavior; used in transistors, solar cells, infrared detectors
- **Medium band gap (1.5-3.5 eV)**: Wider semiconductors for LEDs, power electronics, visible-light photodetectors
- **Large band gap (> 3.5 eV)**: Insulators and ultrawide-gap semiconductors for high-voltage devices, UV optics

## For Solar Cells

The optimal band gap for a single-junction solar cell is approximately 1.34 eV (the Shockley-Queisser limit). Materials with band gaps of 1.0-1.8 eV are prime candidates for photovoltaic absorbers.

## DFT Caveat

Band gaps computed with standard DFT (GGA/PBE) are systematically underestimated by 30-50%. Use them for relative comparisons and screening, not as absolute values.

Question 60

What is the difference between a direct and indirect band gap?

Accepted Answer

In a direct band gap material, the valence band maximum (VBM) and conduction band minimum (CBM) occur at the same point in reciprocal space (the same k-vector). In an indirect band gap material, the VBM and CBM are at different k-points.

## Practical Implications

- **Direct gap materials** (GaAs, CdTe, halide perovskites): Efficient light absorption and emission. Preferred for LEDs, lasers, and solar cells because photons can directly excite electrons across the gap.
- **Indirect gap materials** (Si, Ge, diamond): Weaker optical absorption near the band edge because a phonon (lattice vibration) is needed to conserve crystal momentum. Silicon solar cells work despite this, but require thicker absorber layers (~200 um vs. ~1 um for direct-gap materials).

## How to Check

MatCraft displays "Direct" or "Indirect" on each material's detail page. In the band structure plot, a direct gap shows VBM and CBM at the same k-point, while an indirect gap shows them at different positions along the k-path.

Question 61

What is formation energy?

Accepted Answer

Formation energy (in eV/atom) is the energy change when a compound is formed from its constituent elements in their standard states (e.g., metallic iron, O2 gas, graphite for carbon).

## Interpretation

- **Negative formation energy**: The compound is more stable than the separated elements. Most known stable compounds have negative formation energy.
- **More negative = more stable**: A formation energy of -3.0 eV/atom indicates a stronger thermodynamic driving force than -1.0 eV/atom.
- **Positive formation energy**: The compound is energetically unfavorable relative to the elements, though it may still exist as a metastable phase.

## Relation to Energy Above Hull

Formation energy alone does not tell you if a compound is the most stable phase at its composition. The energy above hull (Ehull) compares against ALL known competing phases, making it a better stability indicator. A material can have a very negative formation energy but still be above the hull if a more stable phase exists at the same composition.

Question 62

What is energy above hull (Ehull)?

Accepted Answer

Energy above hull (Ehull, in eV/atom) measures how far a material is from the thermodynamic convex hull -- the set of most stable phases at each composition in a chemical system.

## Interpretation

- **Ehull = 0**: The material is on the convex hull and is a thermodynamically stable phase
- **Ehull < 0.025 eV/atom**: Very close to stable; likely synthesizable or may exist as a metastable phase
- **Ehull = 0.025 - 0.100 eV/atom**: Moderately metastable; may be accessible under specific synthesis conditions
- **Ehull > 0.100 eV/atom**: Significantly unstable; unlikely to be synthesized in bulk equilibrium conditions

## Why It Matters

Ehull is the single most important stability metric in computational materials science. Screening for Ehull < 0.05 eV/atom is a standard first filter when searching for synthesizable candidate materials.

## How It Is Computed

The convex hull is constructed from formation energies of all known phases in a chemical system. Ehull is the energy difference between a material and the hull at its composition. The Materials Project computes this using the full database of known phases.

Question 63

What are space groups and crystal systems?

Accepted Answer

Space groups classify the complete symmetry of a crystal structure, including translations, rotations, reflections, glide planes, and screw axes. There are 230 unique space groups.

## Crystal Systems

The 230 space groups are organized into 7 crystal systems based on unit cell geometry:

| System | Cell Shape | Example |
|--------|-----------|---------|
| Cubic | a=b=c, all right angles | NaCl (Fm-3m), Si (Fd-3m) |
| Hexagonal | a=b, gamma=120 | ZnO (P6_3mc) |
| Tetragonal | a=b, all right angles | TiO2 rutile (P4_2/mnm) |
| Orthorhombic | All right angles | Many perovskites |
| Monoclinic | One non-right angle | Common in minerals |
| Triclinic | No angle constraints | Least symmetric |
| Trigonal | a=b=c, equal angles | Quartz (P3_121) |

## Why It Matters

Symmetry determines many material properties:
- **Optical**: Cubic materials are optically isotropic
- **Piezoelectric**: Requires non-centrosymmetric space group
- **Elastic**: Higher symmetry means fewer independent elastic constants
- **Electronic**: Band structure topology is constrained by symmetry

Question 64

What units does MatCraft use for material properties?

Accepted Answer

MatCraft uses standard units from computational materials science:

| Property | Unit | Notes |
|----------|------|-------|
| Band gap | eV (electron volts) | 1 eV = 1.602 x 10^-19 J |
| Formation energy | eV/atom | Energy per atom |
| Energy above hull | eV/atom | Stability metric |
| Density | g/cm3 | Mass density |
| Volume | A3 (cubic Angstroms) | Unit cell volume; 1 A = 10^-10 m |
| Lattice parameters | A (Angstroms) | a, b, c lengths |
| Lattice angles | degrees | alpha, beta, gamma |
| Bulk modulus | GPa | Resistance to compression |
| Elastic constants | GPa | Stiffness tensor components |

All energies are referenced to 0 K (zero Kelvin) and zero pressure unless otherwise noted. DFT calculations are performed at the athermal limit (T=0 with no zero-point energy).

Frequently Asked Questions

General

Getting Started

Optimization

Material Domains

Pricing & Plans

Technical

Data Sources

Material Properties

API Usage

Accounts & Access

Scientific Methodology