Documentation

Complete guide to using the PartDB system

Table of Contents

1. Overview

PartDB is a database system designed to track physical parts, their locations, connections, and properties in large-scale experiments. Think of it as an inventory system that also tracks how parts are connected together.

The system was designed for the ETpathfinder project but can be used for any application that needs to track:

  • Physical equipment and components
  • Where things are located (hierarchical locations)
  • How things are connected (e.g., cables to devices)
  • Properties of parts (serial numbers, specifications, etc.)

2. Core Concepts

Types vs. Parts

The most important distinction in PartDB is between Types and Parts:

Analogy:
  • Type = Blueprint or specification (e.g., "iPhone 15" or "BNC Cable")
  • Part = Physical instance (e.g., "My iPhone" or "Cable_001")
Concept Description Example
Type A category or specification Cable, Amplifier, BNC Connector
Part An actual physical object Cable_001, Amplifier_A, Device_042
Subpart A component of a type/part Cable.connectorA, Device.input1
Attribute A property or characteristic serial_number, weight, color
Connection Links between parts Cable_001 connected to Amp_A

Dotted Notation

PartDB uses a simple "dot" notation to refer to parts and their subparts, similar to how you navigate folders on a computer:

Examples:
  • Amplifier_001 - A part named "Amplifier_001"
  • Cable_BNC_001.connectorA - The "connectorA" subpart of cable "Cable_BNC_001"
  • Device_042.input2.pin3 - Pin 3 of input 2 on Device_042

3. Working with Types

Types are the building blocks of PartDB. Before you can add any parts, you need to define their types.

Creating a Type

  1. Go to the Types page
  2. Enter a name for your type (e.g., "Amplifier", "Cable", "BNC")
  3. Click "Add Type"
Naming Rules: Type names must start with a letter or underscore, and can only contain letters, numbers, and underscores. Examples: Amplifier, BNC_Cable, Device_Type1

Adding Subparts to Types

Subparts define the components that make up a type. For example, a Cable type might have two connectors as subparts.

Example: Defining a Cable Type
  1. Create a type called "BNC" (for the connector)
  2. Create a type called "Cable"
  3. On the Cable type page, add two subparts:
    • Subpart name: "connectorA", Type: "BNC"
    • Subpart name: "connectorB", Type: "BNC"

4. Working with Parts

Parts are physical instances of types. Once you've created types, you can add actual parts.

Creating a Part

  1. Go to the Parts page
  2. Select the type of part you want to create
  3. Enter a unique name for the part
  4. Click "Add Part"
Example: Creating Cable Parts

If you created a "Cable" type earlier, you can now create specific cables:

  • Part name: "Cable_BNC_001", Type: "Cable"
  • Part name: "Cable_BNC_002", Type: "Cable"

Location Hierarchy

Parts can be located inside other parts, creating a hierarchy. This is useful for organizing equipment in buildings, rooms, racks, etc.

Example Location Hierarchy:
Building (MainLab)
  └─ Room (Lab_A)
      └─ Rack (Rack_001)
          └─ Shelf (TopShelf)
              └─ Device (Amplifier_001)

5. Understanding Subparts

Subparts are the most powerful (and potentially confusing) feature of PartDB. Here's what you need to know:

The Key Insight: Virtual Subparts

When you add subparts to a type, all parts of that type automatically have those subparts. You don't need to create them individually!

Example:

If your "Cable" type has subparts "connectorA" and "connectorB", then:

  • Cable_BNC_001 automatically has Cable_BNC_001.connectorA and Cable_BNC_001.connectorB
  • Cable_BNC_002 automatically has Cable_BNC_002.connectorA and Cable_BNC_002.connectorB
  • Every cable you create will have these subparts!

Nested Subparts (Two Levels)

Subparts can have their own subparts, allowing up to 2 levels of nesting:

Example: Device with Connectors with Pins
  1. Create type "Pin"
  2. Create type "BNC" with subparts:
    • "center" (type: Pin)
    • "shield" (type: Pin)
  3. Create type "Device" with subparts:
    • "input1" (type: BNC)
    • "output1" (type: BNC)

Now when you create Device_A, you can reference:

  • Device_A.input1 (the input connector)
  • Device_A.input1.center (the center pin of the input)
  • Device_A.output1.shield (the shield pin of the output)

6. Making Connections

Connections represent physical links between parts, like plugging a cable into a device.

Note: Currently, connections need to be created through the search interface or manually in the database. A dedicated connection creation page may be added in the future.

Connection Examples

Typical Connections:
  • Cable_001.connectorA ↔ Amplifier_001.input1
  • Cable_001.connectorB ↔ DAQ_Main.channel1

You can view all connections on the Connections page.

7. Adding Attributes

Attributes are custom properties you can attach to any part, type, or subpart. Examples include serial numbers, specifications, or any other metadata.

Adding an Attribute to a Part

  1. Go to the part's detail page
  2. Scroll to the "Add Attribute" section
  3. Enter the attribute name (e.g., "serial_number")
  4. Enter the value (e.g., "SN-12345")
  5. Select the type (String, Integer, or Float)
  6. Click "Add"
Common Attributes:
Attribute Type Example Value
serial_number String SN-2024-001
weight_kg Float 2.5
gain Integer 100
ip_address String 192.168.1.100
manufacturer String Generic Corp

9. Practical Examples

Example 1: Setting Up a Lab with Cables

Goal: Track cables connecting amplifiers to a DAQ system

Step 1: Create Types

  1. Type: "Pin"
  2. Type: "BNC" with subparts: center (Pin), shield (Pin)
  3. Type: "Cable" with subparts: connectorA (BNC), connectorB (BNC)
  4. Type: "Amplifier" with subparts: input1 (BNC), output1 (BNC)
  5. Type: "DAQ" with subparts: chan1 (BNC), chan2 (BNC), chan3 (BNC)

Step 2: Create Parts

  • Amplifier_001 (type: Amplifier)
  • Amplifier_002 (type: Amplifier)
  • DAQ_Main (type: DAQ)
  • Cable_BNC_001 (type: Cable)
  • Cable_BNC_002 (type: Cable)

Step 3: Add Attributes

  • Amplifier_001: serial_number = "AMP-2024-001", gain = 100
  • Cable_BNC_001: length_m = 5.0, color = "black"

Step 4: Create Connections

  • Cable_BNC_001.connectorA ↔ Amplifier_001.output1
  • Cable_BNC_001.connectorB ↔ DAQ_Main.chan1

Example 2: Location Hierarchy for Equipment

Goal: Track where equipment is located in a building

Step 1: Create Location Types

  1. Type: "Building"
  2. Type: "Room"
  3. Type: "Rack"
  4. Type: "Shelf"

Step 2: Create Location Parts

  • MainLab (type: Building)
  • LabA (type: Room, location: MainLab)
  • Rack001 (type: Rack, location: LabA)
  • TopShelf (type: Shelf, location: Rack001)

Step 3: Place Equipment

  • Amplifier_001 (location: TopShelf)
  • DAQ_Main (location: Rack001)

Tips and Best Practices

  • Plan your types first: Think about the structure before adding parts
  • Use consistent naming: Choose a naming convention (e.g., Cable_BNC_001, Cable_BNC_002)
  • Add attributes liberally: Any useful information can be stored as an attribute
  • Use the search function: It's the fastest way to find and navigate parts
  • Keep location hierarchies simple: Usually 2-3 levels is enough