Nexus Environment Configuration

Nexus Environment Configuration#

Overview#

The Nexus environment enables Tidy3D to connect to custom on-premises or private cloud deployments for enterprise customers.

Note

This feature is for enterprise customers with custom Tidy3D deployments. Most users should use the standard API key setup with the default production environment. See the Installation 👋 guide for standard setup instructions.

Quick Start#

Option 1: Automatic Configuration (Recommended)

When you configure Nexus using the CLI, Tidy3D automatically sets it as your default profile:

tidy3d configure --apikey YOUR_KEY \
  --nexus-url http://your-server

This automatically:

  • Sets API endpoint: http://your-server/tidy3d-api

  • Sets Website endpoint: http://your-server/tidy3d

  • Sets S3 endpoint: http://your-server:9000

  • Sets Nexus as the default profile (persisted across sessions)

After configuration, all your scripts will automatically use Nexus without needing config.switch_profile("nexus").

Option 2: Manual Profile Switching (for temporary use):

For local development on localhost without persistent configuration:

from tidy3d.config import config
config.switch_profile("nexus")

This uses the built-in nexus profile with localhost endpoints (127.0.0.1:5000 for API, 127.0.0.1:9000 for S3).

Advanced setup with individual endpoints:

tidy3d configure --apikey YOUR_KEY \
  --api-endpoint http://your-server/tidy3d-api \
  --website-endpoint http://your-server/tidy3d

Or configure only Nexus endpoints (preserves existing API key):

tidy3d configure --nexus-url http://your-server

Configuration#

Command Syntax#

tidy3d configure [--apikey <key>] [--nexus-url <url> | --api-endpoint <url> --website-endpoint <url>] [OPTIONS]

Options:

  • --apikey <key>: API key (prompts if not provided and no Nexus options given)

  • --nexus-url <url>: Nexus base URL (automatically sets api=/tidy3d-api, web=/tidy3d, s3=:9000)

  • --api-endpoint <url>: Nexus API server URL (e.g., http://server/tidy3d-api)

  • --website-endpoint <url>: Nexus web interface URL (e.g., http://server/tidy3d)

  • --s3-region <region>: S3 region (default: us-east-1)

  • --s3-endpoint <url>: S3 storage URL (e.g., http://server:9000)

  • --ssl-verify / --no-ssl-verify: SSL verification (default: enabled for HTTPS)

  • --enable-caching / --no-caching: Server-side result caching

Examples#

# Simple configuration using nexus-url (recommended)
tidy3d configure --apikey YOUR_KEY \
  --nexus-url http://nexus.company.com

# Configure individual endpoints
tidy3d configure --apikey YOUR_KEY \
  --api-endpoint http://nexus.company.com/tidy3d-api \
  --website-endpoint http://nexus.company.com/tidy3d

# Add Nexus to existing configuration (preserves API key)
tidy3d configure --nexus-url http://nexus.company.com

# Full configuration with all options
tidy3d configure --apikey YOUR_KEY \
  --api-endpoint https://api.company.com/tidy3d-api \
  --website-endpoint https://tidy3d.company.com \
  --s3-region eu-west-1 \
  --s3-endpoint https://s3.company.com:9000 \
  --ssl-verify \
  --enable-caching

Configuration File#

Location:

When you configure Nexus, your custom settings are saved to a profile file:

  • Linux/macOS: ~/.config/tidy3d/profiles/nexus.toml

  • Windows: C:\Users\username\.config\tidy3d\profiles\nexus.toml

The base configuration file (~/.config/tidy3d/config.toml) stores the API key and default profile setting:

# Base config: ~/.config/tidy3d/config.toml
default_profile = "nexus"  # Profile to use by default

[web]
apikey = "your-api-key"

Nexus Profile Format (profiles/nexus.toml):

# Nexus profile: ~/.config/tidy3d/profiles/nexus.toml
[web]
api_endpoint = "http://nexus.company.com/tidy3d-api"
website_endpoint = "http://nexus.company.com/tidy3d"
s3_region = "us-east-1"
ssl_verify = false
enable_caching = false

[web.env_vars]
AWS_ENDPOINT_URL_S3 = "http://nexus.company.com:9000"

The nexus profile file contains only your custom nexus-specific settings (endpoints, SSL, caching). The API key is stored in the base config and shared across all profiles. When the nexus profile is loaded, these settings override the built-in nexus defaults (localhost:5000). The default_profile setting in the base config tells Tidy3D to automatically load the nexus profile on startup.

Note

Automatic Migration: If you have an existing configuration in the old flat format (~/.tidy3d/config), Tidy3D will automatically convert it to the new structured format on first use. Your old configuration will be backed up as config.migrated.

Legacy Format (deprecated)#

For reference, the old flat format that is automatically migrated:

# Old format: ~/.tidy3d/config (automatically migrated)
apikey = "your-api-key"
web_api_endpoint = "http://nexus.company.com/tidy3d-api"
website_endpoint = "http://nexus.company.com/tidy3d"
s3_region = "us-east-1"
s3_endpoint = "http://nexus.company.com:9000"
ssl_verify = false
enable_caching = false

Python Usage#

After CLI Configuration (Automatic)#

Once you’ve configured Nexus using the CLI, no code changes are required. Tidy3D automatically uses your Nexus endpoints:

import tidy3d as td
import tidy3d.web as web

# After running: tidy3d configure --nexus-url http://your-server
# Your scripts automatically use Nexus - no profile switching needed!

sim = td.Simulation(...)
sim_data = web.run(sim, task_name="my_sim")

The CLI configuration persists across sessions, so you only need to configure once.

Manual Profile Switching (Temporary)#

For temporary use or local development without persistent configuration:

from tidy3d.config import config

# Temporarily switch to the built-in nexus profile (localhost defaults)
config.switch_profile("nexus")

# Now run simulations against your local Nexus instance
import tidy3d as td
import tidy3d.web as web

sim = td.Simulation(...)
sim_data = web.run(sim, task_name="my_sim")

The built-in nexus profile uses these default localhost settings:

  • API endpoint: http://127.0.0.1:5000

  • Website endpoint: http://127.0.0.1/tidy3d

  • S3 endpoint: http://127.0.0.1:9000

  • SSL verification: disabled

  • Server-side caching: disabled

Switching Back to Production#

Option 1: Using CLI (Recommended)

tidy3d configure --restore-defaults

This will: - Clear the default_profile setting - Remove the nexus profile file - Revert to production endpoints

Option 2: Using Python

from tidy3d.config import config

# Clear the default profile (reverts to production)
config.set_default_profile(None)
config.save()

Option 3: Switch profiles per session

from tidy3d.config import config

# Temporarily switch to production
config.switch_profile("prod")

Verifying Configuration#

Check your current Nexus configuration:

from tidy3d import config

# Check which profile is active and which is default
print(f"Active profile: {config.profile}")
print(f"Default profile: {config.get_default_profile()}")

# Display current configuration
print(config.format())

# Check specific web settings
print(f"API Endpoint: {config.web.api_endpoint}")
print(f"Website: {config.web.website_endpoint}")
print(f"S3 Region: {config.web.s3_region}")
print(f"SSL Verify: {config.web.ssl_verify}")

# Check S3 endpoint (stored in env_vars)
if "AWS_ENDPOINT_URL_S3" in config.web.env_vars:
    print(f"S3 Endpoint: {config.web.env_vars['AWS_ENDPOINT_URL_S3']}")

Expected output after Nexus configuration:

Active profile: nexus
Default profile: nexus
...

Programmatic Configuration#

Update Nexus settings from Python:

from tidy3d import config

# Update Nexus endpoints
config.update_section("web",
    api_endpoint="http://nexus.company.com/tidy3d-api",
    website_endpoint="http://nexus.company.com/tidy3d",
    s3_region="us-west-2",
    ssl_verify=False,
    enable_caching=True
)

# Set S3 endpoint
config.update_section("web",
    env_vars={"AWS_ENDPOINT_URL_S3": "http://nexus.company.com:9000"}
)

# Save changes to disk
config.save()

Environment Variables#

Override any setting temporarily using environment variables:

# Override API endpoint
export TIDY3D_WEB__API_ENDPOINT="http://other-server/tidy3d-api"

# Override S3 endpoint
export TIDY3D_WEB__ENV_VARS__AWS_ENDPOINT_URL_S3="http://other-s3:9000"

# Override SSL verification
export TIDY3D_WEB__SSL_VERIFY=false

Managing Configuration#

Change Default Profile#

Set or clear the default profile:

from tidy3d import config

# Set nexus as default
config.set_default_profile("nexus")

# Clear default profile (revert to production)
config.set_default_profile(None)

# Check current default
print(config.get_default_profile())

Reset to Defaults#

Reset configuration to default values (including clearing default profile):

tidy3d config reset

Or from Python:

from tidy3d import config
config.reset_to_defaults()
config.save()

View Configuration#

Display current configuration:

python -c "from tidy3d import config; print(config.format())"

Or interactively:

from tidy3d import config

# Print formatted configuration
print(config)

# Or just web section
print(config.web)

Migrate Legacy Configuration#

Manually migrate old configuration to new format:

tidy3d config migrate

Options:

  • --delete-legacy: Remove old ~/.tidy3d directory after migration

  • --overwrite: Overwrite existing new-format configuration

Remove Configuration#

To completely remove Nexus configuration:

# Linux/macOS
rm ~/.config/tidy3d/config.toml

# Or reset to defaults
tidy3d config reset

# Then reconfigure with standard API key
tidy3d configure --apikey YOUR_API_KEY

Troubleshooting#

Verify Configuration#

Check that your Nexus configuration is active:

from tidy3d import config

print("=== Tidy3D Configuration ===")
print(f"API Endpoint: {config.web.api_endpoint}")
print(f"Website: {config.web.website_endpoint}")

# Verify it's not using production
if "simulation.cloud" in str(config.web.api_endpoint):
    print("??  Using production, not Nexus!")
else:
    print("? Using custom Nexus deployment")

Test Connectivity#

Verify your Nexus server is accessible:

# Test API endpoint
curl http://your-nexus-server/tidy3d-api/health

# Or with Python
python -c "import requests; from tidy3d import config; \
print(requests.get(f'{config.web.api_endpoint}/health').text)"

Check S3 Configuration#

Verify S3 endpoint configuration:

from tidy3d import config

if config.web.env_vars and "AWS_ENDPOINT_URL_S3" in config.web.env_vars:
    s3_endpoint = config.web.env_vars["AWS_ENDPOINT_URL_S3"]
    print(f"S3 Endpoint: {s3_endpoint}")
else:
    print("Using default AWS S3")

Legacy Environment Check (Deprecated)#

For backward compatibility, the old Environment API still works:

# Old API (deprecated, but still functional)
from tidy3d.web.core.environment import Env
print(f"Environment: {Env.current.name}")
print(f"API Endpoint: {Env.current.web_api_endpoint}")

Warning

The Env API is deprecated and will be removed in a future version. Use tidy3d.config instead.

Common Issues#

Issue: Still connecting to production instead of Nexus

Solution: Check if the default profile is set correctly:

from tidy3d import config
print(f"Active profile: {config.profile}")
print(f"Default profile: {config.get_default_profile()}")
print(f"API Endpoint: {config.web.api_endpoint}")

If the default profile is not "nexus", reconfigure:

tidy3d configure --nexus-url http://your-server

Issue: Configuration not taking effect

Solution: Environment variables override the default profile. Check for overrides:

# Check for environment variable overrides
env | grep TIDY3D

If TIDY3D_CONFIG_PROFILE, TIDY3D_PROFILE, or TIDY3D_ENV is set, it will override the default profile from config.

Issue: Old config file still exists

The old flat config file is automatically backed up during migration. It’s safe to delete:

# Old config is backed up as config.migrated
ls ~/.tidy3d/
# You can safely remove: rm ~/.tidy3d/config.migrated

Issue: API key validation fails

Ensure you’re validating against your Nexus endpoint:

tidy3d configure --apikey YOUR_KEY \
  --nexus-url http://your-nexus-server

Advanced Topics#

Profile Selection Priority#

Tidy3D uses the following priority order when determining which profile to load:

  1. Explicit parameter: ConfigManager(profile="dev")

  2. Environment variables: TIDY3D_CONFIG_PROFILE, TIDY3D_PROFILE, or TIDY3D_ENV

  3. Default profile in config: default_profile in config.toml

  4. Fallback: "default" profile (production)

This means environment variables always override the default profile setting, allowing temporary overrides without changing the configuration file.

Multiple Configurations (Profiles)#

Switch between different Nexus deployments:

from tidy3d import config

# Switch to a different profile
config.switch_profile("dev")

# Configure for dev environment
config.update_section("web",
    api_endpoint="http://dev-nexus/tidy3d-api",
    website_endpoint="http://dev-nexus/tidy3d"
)
config.save()

# Switch back to default
config.switch_profile("default")

Or via environment variable:

# Use dev profile
export TIDY3D_CONFIG_PROFILE=dev
python your_script.py

Custom S3 Configuration#

For Nexus deployments with MinIO or other S3-compatible storage:

from tidy3d import config

config.update_section("web",
    s3_region="us-east-1",
    env_vars={
        "AWS_ENDPOINT_URL_S3": "http://minio.company.com:9000",
        # Optional: Add other AWS config
        "AWS_ACCESS_KEY_ID": "your-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret"
    }
)
config.save()

See Also#

  • submit_simulations - Submitting and managing simulations

  • Installation 👋 - Installation and API key setup

Contents