Component properties reference

Complete reference of all electrical component properties, required fields, valid ranges, and units.

Property types

All components share base properties plus type-specific electrical properties:

Base properties (all components):

• Name (string, 1-100 characters, required)
• Position X (number, canvas coordinate)
• Position Y (number, canvas coordinate)
• Project ID (UUID, immutable)
• Created at (timestamp, auto-generated)
• Updated at (timestamp, auto-updated)

Electrical properties:

• Component-specific ratings and parameters
• Units specified per property
• Validation ranges enforce electrical reality
• Required vs optional indicated below

Bus properties

Distribution buses and connection points:

Notes:

• Exactly one slack bus per network required for power flow
• Bus handles are dynamic (unlimited connections)
• Voltage tolerance: ±10% typically acceptable
• Short-circuit rating must exceed calculated fault current

Common voltage levels:

• Low voltage: 0.208, 0.48, 0.6 kV
• Medium voltage: 4.16, 13.8, 23, 34.5 kV
• High voltage: 69, 115, 138, 230 kV

Cable properties

Conductors connecting components:

Installation types:

• underground (conduit, direct burial)
• cable_tray
• open_air
• enclosed_raceway

Cable variants (read-only from system database):

• Conductor size (AWG or kcmil)
• Conductor material (CU, AL)
• Insulation type (THHN, XHHW, TC-ER, MV-90, etc.)
• Rated amperage at 75°C
• Resistance per km (ohms/km)
• Reactance per km (ohms/km)
• Capacitance per km (nF/km)

Notes:

• 246 cable variants across 12 series in system database
• Length converted internally between m/km/ft based on user preference
• Parallel runs multiply ampacity (with derating)
• Installation type affects ampacity derating

Transformer properties

Voltage conversion equipment:

Vector groups:

• Dyn11 (Delta primary, wye secondary, 30° phase shift)
• Yy0 (Wye-wye, no phase shift)
• Dd0 (Delta-delta, no phase shift)
• YNd1 (Wye-delta with neutral)

Default impedances by kVA:

• 10-100 kVA: 3-4%
• 100-500 kVA: 4-5%
• 500-2500 kVA: 5-6%
• 2500+ kVA: 6-8%

Notes:

• Impedance limits fault current on secondary
• Tap position adjusts secondary voltage
• Vector group affects zero-sequence impedance

Load properties

Generic electrical loads:

Load types:

• constant_power: P and Q constant regardless of voltage
• constant_impedance: P and Q vary with V²
• constant_current: P varies linearly with V (future)

Power factor:

• Lagging (inductive): 0.7-0.95 typical for motors, transformers
• Unity: 1.0 for resistive loads
• Leading (capacitive): Rare in loads, usually from power factor correction

Notes:

• Reactive power calculated from active power × tan(arccos(PF))
• Negative reactive power = leading (capacitive)
• Load profile affects power flow calculations (future feature)
• ratedCurrent is a design input (connected/nameplate-style), not solved running current.
• Standard branch cable and OCPD auto-sizing use ratedCurrent when provided, otherwise derive current from active power, voltage, and power factor.
• Simple branch cable and OCPD auto-sizing use connected/design load current. demandFactor is used for operating/load-flow and aggregate sizing, not to reduce branch equipment size.
• Use the branch design pin/lock path when a branch fuse, breaker, or cable is intentionally limited below connected load capability.

Motor properties

Rotating mechanical loads:

Starting methods:

• DOL (Direct-on-line): Full voltage start, 5-8× FLC starting current
• Soft start: Reduced inrush, 3-4× FLC
• VFD (Variable frequency drive): Smooth start, ~1.5× FLC

Full-load current:

• Auto-calculated from NEC 430.248 (1-phase) or 430.250 (3-phase)
• Based on rated HP and voltage
• Used for conductor and OCPD sizing

Notes:

• Motor FLC differs from locked-rotor current (LRC)
• Efficiency affects active power draw
• Power factor affects reactive power

Generator properties

On-site power generation:

Reactances:

• Xd: Steady-state (used for power flow)
• Xd': Transient (fault clearing time)
• Xd'': Subtransient (first few cycles, short-circuit)

Notes:

• Subtransient reactance determines initial fault contribution
• Lower reactance = higher fault current contribution
• Values in per-unit on generator base MVA

Utility feed properties

External grid connections:

Short-circuit MVA:

• Available fault current from utility
• Provided by utility at service entrance
• Infinite bus assumption (constant voltage source)

X/R ratio:

• Reactance to resistance ratio
• Affects fault current decay
• Typical: 10-20 for MV systems, 3-8 for LV

Input methods:

• MVA: Specify short-circuit MVA directly
• kA: Specify fault current in kA (converts to MVA)

Notes:

• Acts as slack bus for power flow (sets voltage reference)
• Represents grid contribution to fault current
• Typically one per facility (two for redundancy)

Protection device properties

Breakers and fuses:

Device types:

• hv_breaker (>1kV, power circuit breaker)
• lv_breaker (<1kV, molded case breaker)
• fuse (current-limiting)

Interrupting capacity (AIC):

• Must exceed fault current at installation point
• Standard ratings: 10, 14, 22, 25, 42, 65, 100, 200 kA
• Higher ratings cost more

Trip unit types:

• thermal_magnetic: Bimetal thermal + magnetic instant
• electronic: Digital trip, adjustable settings
• motor_protection: Overload class, motor-specific

Notes:

• Rated current must be ≥ standard NEC size
• Standard sizes per NEC 240.6
• Fuses have higher AIC than breakers typically

Property validation

All properties validated on save:

String properties:

• Max length enforced
• Empty strings rejected
• Special characters sanitized

Numeric properties:

• Range validation (min/max)
• Precision limits (decimal places)
• Units conversion applied
• NaN and Infinity rejected

Enum properties:

• Value must match allowed list
• Case-sensitive matching
• Invalid values rejected with error message

Required properties:

• Cannot be null or undefined
• Must be present on component creation
• Cannot be deleted (can be zero if valid)

Units and conversion

Internal storage units (SI):

Voltage: kV (kilovolts) Current: A (amperes) or kA (kiloamperes) Power: MW (megawatts), MVAR (megavars), MVA (megavolt-amperes) Resistance/Reactance: ohms or ohms/km Capacitance: nF/km (nanofarads per kilometer) Length: km (kilometers)

Display units (user preference):

• Imperial: feet for cable length
• Metric: meters for cable length
• Mixed: Common US practice

Conversion automatic based on user settings.

Related topics

• Understanding components - Component roles and functions
• Connection rules - Valid electrical connections
• Electrical concepts - Power system fundamentals