@tscircuit/props 0.0.590 → 0.0.592

package/lib/components/analogacsweepsimulation.ts

@@ -0,0 +1,85 @@
+import { frequency } from "circuit-json"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+import {
+  analogAnalysisSimulationBaseProps,
+  type AnalogAnalysisSimulationBaseProps,
+} from "./analogsimulation"
+
+export interface AnalogAcSweepSimulationProps
+  extends AnalogAnalysisSimulationBaseProps {
+  /** Frequency spacing used by the AC analysis. */
+  sweepType: "linear" | "decade" | "octave"
+  /** First positive frequency. Raw numbers are hertz. */
+  startFrequency: number | string
+  /** Last frequency, which must be greater than startFrequency. Raw numbers are hertz. */
+  stopFrequency: number | string
+  /** Samples per decade or octave; required for non-linear sweeps. */
+  samplesPerInterval?: number
+  /** Total samples; required for linear sweeps. */
+  sampleCount?: number
+}
+
+export const analogAcSweepSimulationProps = z
+  .object({
+    ...analogAnalysisSimulationBaseProps,
+    sweepType: z.enum(["linear", "decade", "octave"]),
+    startFrequency: frequency.refine(
+      (startFrequencyHz) => startFrequencyHz > 0,
+      "startFrequency must be positive",
+    ),
+    stopFrequency: frequency.refine(
+      (stopFrequencyHz) => stopFrequencyHz > 0,
+      "stopFrequency must be positive",
+    ),
+    samplesPerInterval: z.number().int().positive().optional(),
+    sampleCount: z.number().int().positive().optional(),
+  })
+  .superRefine((simulation, context) => {
+    if (simulation.stopFrequency <= simulation.startFrequency) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["stopFrequency"],
+        message: "stopFrequency must be greater than startFrequency",
+      })
+    }
+
+    if (simulation.sweepType === "linear") {
+      if (simulation.sampleCount === undefined) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["sampleCount"],
+          message: "sampleCount is required for a linear AC sweep",
+        })
+      }
+      if (simulation.samplesPerInterval !== undefined) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["samplesPerInterval"],
+          message:
+            "samplesPerInterval is only valid for decade or octave sweeps",
+        })
+      }
+      return
+    }
+
+    if (simulation.samplesPerInterval === undefined) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["samplesPerInterval"],
+        message: "samplesPerInterval is required for decade or octave sweeps",
+      })
+    }
+    if (simulation.sampleCount !== undefined) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["sampleCount"],
+        message: "sampleCount is only valid for a linear sweep",
+      })
+    }
+  })
+
+expectTypesMatch<
+  AnalogAcSweepSimulationProps,
+  z.input<typeof analogAcSweepSimulationProps>
+>(true)

package/lib/components/analogdcoperatingpointsimulation.ts

@@ -0,0 +1,18 @@
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+import {
+  analogAnalysisSimulationBaseProps,
+  type AnalogAnalysisSimulationBaseProps,
+} from "./analogsimulation"
+
+export type AnalogDcOperatingPointSimulationProps =
+  AnalogAnalysisSimulationBaseProps
+
+export const analogDcOperatingPointSimulationProps = z.object({
+  ...analogAnalysisSimulationBaseProps,
+})
+
+expectTypesMatch<
+  AnalogDcOperatingPointSimulationProps,
+  z.input<typeof analogDcOperatingPointSimulationProps>
+>(true)

package/lib/components/analogdcsweepsimulation.ts

@@ -0,0 +1,50 @@
+import { current, voltage } from "circuit-json"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+import {
+  analogAnalysisSimulationBaseProps,
+  type AnalogAnalysisSimulationBaseProps,
+} from "./analogsimulation"
+
+export interface AnalogDcSweepSimulationProps
+  extends AnalogAnalysisSimulationBaseProps {
+  /** Selector for the independent voltage or current source being swept. */
+  sweepSource: string
+  /** First source level. Raw numbers use volts or amperes according to the source. */
+  sweepStart: number | string
+  /** Last source level. Raw numbers use volts or amperes according to the source. */
+  sweepStop: number | string
+  /** Nonzero increment directed from sweepStart toward sweepStop. */
+  sweepStep: number | string
+}
+
+const dcSweepQuantity = z.union([voltage, current])
+
+export const analogDcSweepSimulationProps = z
+  .object({
+    ...analogAnalysisSimulationBaseProps,
+    sweepSource: z.string().min(1),
+    sweepStart: dcSweepQuantity,
+    sweepStop: dcSweepQuantity,
+    sweepStep: dcSweepQuantity.refine(
+      (sweepStep) => sweepStep !== 0,
+      "sweepStep must be nonzero",
+    ),
+  })
+  .superRefine((simulation, context) => {
+    if (
+      Math.sign(simulation.sweepStop - simulation.sweepStart) !==
+      Math.sign(simulation.sweepStep)
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["sweepStep"],
+        message: "sweepStep must move from sweepStart toward sweepStop",
+      })
+    }
+  })
+
+expectTypesMatch<
+  AnalogDcSweepSimulationProps,
+  z.input<typeof analogDcSweepSimulationProps>
+>(true)

package/lib/components/analogsimulation.ts

@@ -1,6 +1,7 @@
 import { ms } from "circuit-json"
 import type { AutocompleteString } from "lib/common/autocomplete"
 import { expectTypesMatch } from "lib/typecheck"
+import type { ReactNode } from "react"
 import { z } from "zod"
 
 export interface AnalogSimulationProps {
@@ -32,6 +33,27 @@ const spiceOptions = z.object({
   vntol: z.union([z.number(), z.string()]).optional(),
 })
 
+export interface AnalogAnalysisSimulationBaseProps {
+  /** Stable identity for the simulation experiment. */
+  name?: string
+  /** SPICE implementation used to run this analysis. */
+  spiceEngine?: AutocompleteString<"spicey" | "ngspice">
+  /** Numerical solver settings forwarded to the selected SPICE engine. */
+  spiceOptions?: SpiceOptions
+  /** Render each probe with an independent vertical graph scale. */
+  graphIndependentAxes?: boolean
+  /** Optional nested sweep parameter for repeated analysis runs. */
+  children?: ReactNode
+}
+
+export const analogAnalysisSimulationBaseProps = {
+  name: z.string().optional(),
+  spiceEngine: spiceEngine.optional(),
+  spiceOptions: spiceOptions.optional(),
+  graphIndependentAxes: z.boolean().optional(),
+  children: z.custom<ReactNode>().optional(),
+}
+
 export const analogSimulationProps = z.object({
   name: z.string().optional(),
   simulationType: z

package/lib/components/analogsweepparameter.ts

@@ -0,0 +1,213 @@
+import {
+  capacitance,
+  current,
+  inductance,
+  resistance,
+  voltage,
+} from "circuit-json"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+
+interface AnalogSweepCoordinatesProps {
+  /** Stable identity for this sweep parameter. */
+  name?: string
+  /** Explicit parameter coordinates. Cannot be combined with start/stop/step. */
+  values?: Array<number | string>
+  /** First generated parameter coordinate. Requires stop and step. */
+  start?: number | string
+  /** Last generated parameter coordinate. Requires start and step. */
+  stop?: number | string
+  /** Nonzero parameter increment directed from start toward stop. */
+  step?: number | string
+}
+
+export interface AnalogResistanceSweepParameterProps
+  extends AnalogSweepCoordinatesProps {
+  parameterType: "resistance"
+  /** Selector for the resistor whose simulation-only resistance is swept. */
+  resistorRef: string
+}
+
+export interface AnalogCapacitanceSweepParameterProps
+  extends AnalogSweepCoordinatesProps {
+  parameterType: "capacitance"
+  /** Selector for the capacitor whose simulation-only capacitance is swept. */
+  capacitorRef: string
+}
+
+export interface AnalogInductanceSweepParameterProps
+  extends AnalogSweepCoordinatesProps {
+  parameterType: "inductance"
+  /** Selector for the inductor whose simulation-only inductance is swept. */
+  inductorRef: string
+}
+
+export interface AnalogVoltageSweepParameterProps
+  extends AnalogSweepCoordinatesProps {
+  parameterType: "voltage"
+  /** Net whose simulation-only voltage is swept. */
+  net: string
+}
+
+export interface AnalogCurrentSweepParameterProps
+  extends AnalogSweepCoordinatesProps {
+  parameterType: "current"
+  /** Selector for the current source whose simulation-only current is swept. */
+  currentSourceRef: string
+}
+
+const resistanceSweepQuantity = resistance.pipe(z.number())
+const capacitanceSweepQuantity = capacitance.pipe(z.number())
+const inductanceSweepQuantity = inductance.pipe(z.number())
+const voltageSweepQuantity = voltage.pipe(z.number())
+const currentSweepQuantity = current.pipe(z.number())
+
+const createAnalogSweepCoordinateProps = (
+  sweepQuantity: z.ZodType<number, z.ZodTypeDef, number | string>,
+) => ({
+  name: z.string().optional(),
+  values: z.array(sweepQuantity).min(1).optional(),
+  start: sweepQuantity.optional(),
+  stop: sweepQuantity.optional(),
+  step: sweepQuantity.optional(),
+})
+
+export const analogResistanceSweepParameterProps = z
+  .object({
+    ...createAnalogSweepCoordinateProps(resistanceSweepQuantity),
+    parameterType: z.literal("resistance"),
+    resistorRef: z.string().min(1),
+  })
+  .strict()
+
+export const analogCapacitanceSweepParameterProps = z
+  .object({
+    ...createAnalogSweepCoordinateProps(capacitanceSweepQuantity),
+    parameterType: z.literal("capacitance"),
+    capacitorRef: z.string().min(1),
+  })
+  .strict()
+
+export const analogInductanceSweepParameterProps = z
+  .object({
+    ...createAnalogSweepCoordinateProps(inductanceSweepQuantity),
+    parameterType: z.literal("inductance"),
+    inductorRef: z.string().min(1),
+  })
+  .strict()
+
+export const analogVoltageSweepParameterProps = z
+  .object({
+    ...createAnalogSweepCoordinateProps(voltageSweepQuantity),
+    parameterType: z.literal("voltage"),
+    net: z.string().min(1),
+  })
+  .strict()
+
+export const analogCurrentSweepParameterProps = z
+  .object({
+    ...createAnalogSweepCoordinateProps(currentSweepQuantity),
+    parameterType: z.literal("current"),
+    currentSourceRef: z.string().min(1),
+  })
+  .strict()
+
+interface ParsedAnalogSweepCoordinates {
+  values?: number[]
+  start?: number
+  stop?: number
+  step?: number
+}
+
+const validateAnalogSweepCoordinates = (
+  sweepCoordinates: ParsedAnalogSweepCoordinates,
+  context: z.RefinementCtx,
+) => {
+  const hasExplicitSweepCoordinates = sweepCoordinates.values !== undefined
+  const rangeCoordinateCount = [
+    sweepCoordinates.start,
+    sweepCoordinates.stop,
+    sweepCoordinates.step,
+  ].filter((rangeCoordinate) => rangeCoordinate !== undefined).length
+  const hasRangeCoordinates = rangeCoordinateCount > 0
+
+  if (hasExplicitSweepCoordinates === hasRangeCoordinates) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Provide either values or start/stop/step",
+    })
+    return
+  }
+
+  if (rangeCoordinateCount !== 0 && rangeCoordinateCount !== 3) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "start, stop, and step must be provided together",
+    })
+    return
+  }
+
+  if (sweepCoordinates.step === 0) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["step"],
+      message: "step must be nonzero",
+    })
+  }
+
+  if (
+    sweepCoordinates.start !== undefined &&
+    sweepCoordinates.stop !== undefined &&
+    sweepCoordinates.step !== undefined &&
+    Math.sign(sweepCoordinates.stop - sweepCoordinates.start) !==
+      Math.sign(sweepCoordinates.step)
+  ) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["step"],
+      message: "step must move from start toward stop",
+    })
+  }
+}
+
+export type AnalogSweepParameterProps =
+  | AnalogResistanceSweepParameterProps
+  | AnalogCapacitanceSweepParameterProps
+  | AnalogInductanceSweepParameterProps
+  | AnalogVoltageSweepParameterProps
+  | AnalogCurrentSweepParameterProps
+
+export const analogSweepParameterProps = z
+  .discriminatedUnion("parameterType", [
+    analogResistanceSweepParameterProps,
+    analogCapacitanceSweepParameterProps,
+    analogInductanceSweepParameterProps,
+    analogVoltageSweepParameterProps,
+    analogCurrentSweepParameterProps,
+  ])
+  .superRefine(validateAnalogSweepCoordinates)
+
+expectTypesMatch<
+  AnalogResistanceSweepParameterProps,
+  z.input<typeof analogResistanceSweepParameterProps>
+>(true)
+expectTypesMatch<
+  AnalogCapacitanceSweepParameterProps,
+  z.input<typeof analogCapacitanceSweepParameterProps>
+>(true)
+expectTypesMatch<
+  AnalogInductanceSweepParameterProps,
+  z.input<typeof analogInductanceSweepParameterProps>
+>(true)
+expectTypesMatch<
+  AnalogVoltageSweepParameterProps,
+  z.input<typeof analogVoltageSweepParameterProps>
+>(true)
+expectTypesMatch<
+  AnalogCurrentSweepParameterProps,
+  z.input<typeof analogCurrentSweepParameterProps>
+>(true)
+expectTypesMatch<
+  AnalogSweepParameterProps,
+  z.input<typeof analogSweepParameterProps>
+>(true)

package/lib/components/analogtransientsimulation.ts

@@ -0,0 +1,47 @@
+import { ms } from "circuit-json"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+import {
+  analogAnalysisSimulationBaseProps,
+  type AnalogAnalysisSimulationBaseProps,
+} from "./analogsimulation"
+
+export interface AnalogTransientSimulationProps
+  extends AnalogAnalysisSimulationBaseProps {
+  /** Simulation duration. Raw numbers are milliseconds. Defaults to 10ms. */
+  duration?: number | string
+  /** Time at which recording starts. Raw numbers are milliseconds. Defaults to 0ms. */
+  startTime?: number | string
+  /** Maximum simulation timestep. Raw numbers are milliseconds. Defaults to 0.01ms. */
+  timePerStep?: number | string
+}
+
+const positiveMilliseconds = ms.refine(
+  (milliseconds) => milliseconds > 0,
+  "Time must be positive",
+)
+
+export const analogTransientSimulationProps = z
+  .object({
+    ...analogAnalysisSimulationBaseProps,
+    duration: positiveMilliseconds.default("10ms"),
+    startTime: ms.default("0ms"),
+    timePerStep: positiveMilliseconds.default("0.01ms"),
+  })
+  .superRefine((simulation, context) => {
+    if (
+      simulation.startTime < 0 ||
+      simulation.startTime > simulation.duration
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["startTime"],
+        message: "startTime must be between zero and duration",
+      })
+    }
+  })
+
+expectTypesMatch<
+  AnalogTransientSimulationProps,
+  z.input<typeof analogTransientSimulationProps>
+>(true)

package/lib/components/currentsource.ts

@@ -21,6 +21,10 @@ export interface CurrentSourceProps<PinLabel extends string = string>
   waveShape?: WaveShape
   phase?: number | string
   dutyCycle?: number | string
+  /** Small-signal AC magnitude. Raw numbers are amperes. */
+  acMagnitude?: number | string
+  /** Small-signal AC phase. Raw numbers are degrees. */
+  acPhase?: number | string
   connections?: Connections<CurrentSourcePinLabels>
 }
 
@@ -49,6 +53,8 @@ export const currentSourceProps = commonComponentProps.extend({
   waveShape: z.enum(["sinewave", "square", "triangle", "sawtooth"]).optional(),
   phase: rotation.optional(),
   dutyCycle: percentage.optional(),
+  acMagnitude: current.optional(),
+  acPhase: rotation.optional(),
   connections: createConnectionsProp(currentSourcePinLabels).optional(),
 })
 

package/lib/components/schematic-symbol.ts

@@ -0,0 +1,59 @@
+import { rotation } from "circuit-json"
+import { connectionTarget } from "lib/common/connectionsProp"
+import { distance, type Distance } from "lib/common/distance"
+import { expectTypesMatch } from "lib/typecheck"
+import type { Connections } from "lib/utility-types/connections-and-selectors"
+import { z } from "zod"
+
+/**
+ * Places a named schematic-symbol representation of an existing physical
+ * component. The connection keys are labels exposed by `symbolName`; each
+ * value selects the corresponding port on the component referenced by
+ * `chipRef`.
+ *
+ * This is a schematic-only projection, so it accepts only the identity,
+ * connection, and schematic placement props it needs.
+ */
+export interface SchematicSymbolProps {
+  /** Stable name for this representation, such as `A` or `B`. */
+  name: string
+  /** Optional human-facing name shown in the schematic. */
+  displayName?: string
+  /** Selector for the physical component represented by this symbol. */
+  chipRef?: string
+  /** Name of the symbol from the schematic-symbol library. */
+  symbolName: string
+  /** Maps symbol port labels to physical component port selectors. */
+  connections?: Connections
+  schX?: Distance
+  schY?: Distance
+  schRotation?: number | string
+  schSectionName?: string
+  schSheetName?: string
+}
+
+const schematicSymbolConnections = z
+  .custom<Connections>()
+  .pipe(z.record(z.string(), connectionTarget))
+  .refine((value) => Object.keys(value).length > 0, {
+    message: "connections must map at least one schematic symbol port",
+  })
+
+export const schematicSymbolProps = z.object({
+  name: z.string().min(1),
+  displayName: z.string().optional(),
+  chipRef: z.string().min(1).optional(),
+  symbolName: z.string().min(1),
+  connections: schematicSymbolConnections.optional(),
+  schX: distance.optional(),
+  schY: distance.optional(),
+  schRotation: rotation.optional(),
+  schSectionName: z.string().optional(),
+  schSheetName: z.string().optional(),
+})
+
+export type InferredSchematicSymbolProps = z.input<typeof schematicSymbolProps>
+
+expectTypesMatch<SchematicSymbolProps, z.input<typeof schematicSymbolProps>>(
+  true,
+)

package/lib/components/voltagesource.ts

@@ -27,6 +27,10 @@ export interface VoltageSourceProps<PinLabel extends string = string>
   fallTime?: number | string
   pulseWidth?: number | string
   period?: number | string
+  /** Small-signal AC magnitude. Raw numbers are volts. */
+  acMagnitude?: number | string
+  /** Small-signal AC phase. Raw numbers are degrees. */
+  acPhase?: number | string
   connections?: Connections<VoltageSourcePinLabels>
 }
 
@@ -60,6 +64,8 @@ export const voltageSourceProps = commonComponentProps.extend({
   fallTime: ms.optional(),
   pulseWidth: ms.optional(),
   period: ms.optional(),
+  acMagnitude: voltage.optional(),
+  acPhase: rotation.optional(),
   connections: createConnectionsProp(voltageSourcePinLabels).optional(),
 })
 

package/lib/index.ts

@@ -69,6 +69,11 @@ export * from "./components/netlabel"
 export * from "./components/push-button"
 export * from "./components/subcircuit"
 export * from "./components/analogsimulation"
+export * from "./components/analogtransientsimulation"
+export * from "./components/analogdcoperatingpointsimulation"
+export * from "./components/analogdcsweepsimulation"
+export * from "./components/analogacsweepsimulation"
+export * from "./components/analogsweepparameter"
 export * from "./components/autoroutingphase"
 export * from "./components/spicemodel"
 export * from "./manual-edits"
@@ -104,6 +109,7 @@ export * from "./components/ammeter"
 export * from "./components/schematic-arc"
 export * from "./components/toolingrail"
 export * from "./components/schematic-box"
+export * from "./components/schematic-symbol"
 export * from "./components/schematic-circle"
 export * from "./components/schematic-rect"
 export * from "./components/schematic-line"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/props",
-  "version": "0.0.590",
+  "version": "0.0.592",
   "description": "Props for tscircuit builtin component types",
   "main": "dist/index.js",
   "type": "module",