From cf5f5a7e096c131ca3d207cf67aadf383b9e60a8 Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Thu, 28 Apr 2022 19:52:57 +0530 Subject: [PATCH 1/3] Copy over docstrings from old branch --- src/Electrical/Analog/ideal_components.jl | 101 +++++++-- src/Electrical/Analog/sensors.jl | 91 +++++++- src/Electrical/Analog/sources.jl | 258 +++++++++++++++++----- src/Electrical/Digital/components.jl | 107 +++++++++ src/Electrical/Digital/gates.jl | 91 ++++++++ src/Electrical/Digital/sources.jl | 46 ++++ src/Electrical/utils.jl | 39 +++- 7 files changed, 652 insertions(+), 81 deletions(-) diff --git a/src/Electrical/Analog/ideal_components.jl b/src/Electrical/Analog/ideal_components.jl index c5f76d571..639d10d5e 100644 --- a/src/Electrical/Analog/ideal_components.jl +++ b/src/Electrical/Analog/ideal_components.jl @@ -1,7 +1,13 @@ """ - Ground(;name) +```julia +function Ground(; name) +``` -Ground of an electrical circuit. The potential at the ground node is zero. Every circuit must have one ground node. +Ground node with the potential of zero and connector `g`. Every circuit must have one ground +node. + +# Connectors +- `g` """ function Ground(;name) @named g = Pin() @@ -10,12 +16,25 @@ function Ground(;name) end """ - Resistor(;name, R=1.0) +```julia +function Resistor(; name, R = 1.0) +``` + +Creates an ideal Resistor following Ohm's Law. + +# States +- `v(t)`: [`V`] + The voltage across the resistor, given by `p.i * R` -Ideal linear electrical resistor. +# Connectors +- `p` + Positive pin +- `n` + Negative pin # Parameters: -- `R`: [Ω] Resistance +- `R`: [`Ω`] + Resistance """ function Resistor(;name, R=1.0) @named oneport = OnePort() @@ -28,13 +47,27 @@ function Resistor(;name, R=1.0) end """ - Capacitor(;name, C=1.0, v_start=0.0) +```julia +function Capacitor(; name, C = 1.0) +``` + +Creates an ideal Capacitor. + +# States +- `v(t)`: [`V`] + The voltage across the capacitor, given by `D(v) ~ p.i / C` -Ideal linear electrical capacitor. +# Connectors +- `p` + Positive pin +- `n` + Negative pin # Parameters: -- `C`: [F] Capacity -- `v_start`: [V] Initial voltage of capacitor +- `C`: [`F`] + Capacitance +- `v_start`: [`V`] + Initial voltage of capacitor """ function Capacitor(;name, C=1.0, v_start=0.0) @named oneport = OnePort(;v_start=v_start) @@ -47,13 +80,27 @@ function Capacitor(;name, C=1.0, v_start=0.0) end """ - Inductor(;name, L=1.0e-6, i_start=0.0) +```julia +function Inductor(; name, L = 1.0) +``` -Ideal linear electrical inductor. +Creates an ideal Inductor. + +# States +- `v(t)`: [`V`] + The voltage across the inductor, given by `D(p.i) ~ v / L` + +# Connectors +- `p` + Positive pin +- `n` + Negative pin # Parameters: -- `L`: [H] Inductance -- `i_start`: [A] Initial current through inductor +- `L`: [`H`] + Inductance +- `i_start`: [`A`] + Initial current through inductor """ function Inductor(;name, L=1.0e-6, i_start=0.0) @named oneport = OnePort(;i_start=i_start) @@ -66,11 +113,33 @@ function Inductor(;name, L=1.0e-6, i_start=0.0) end """ - IdealOpAmp(;name) +```julia +function IdealOpAmp(; name) +``` Ideal operational amplifier (norator-nullator pair). -The ideal OpAmp is a two-port. The left port is fixed to v1=0 and i1=0 (nullator). -At the right port both any voltage v2 and any current i2 are possible (norator). +The ideal OpAmp is a two-port. The left port is fixed to `v1 = 0` and `i1 = 0` (nullator). +At the right port both any voltage `v2` and any current `i2` are possible (norator). + +# States +- `v1(t)`: [`V`] + Voltage of left port +- `v2(t)`: [`V`] + Voltage of right port +- `i1(t)`: [`A`] + Current of left port +- `i2(t)`: [`A`] + Current of right port + +# Connectors +- `p1` + Positive pin (left port) +- `p2` + Positive pin (right port) +- `n1` + Negative pin (left port) +- `n2` + Negative pin (right port) """ function IdealOpAmp(;name) @named p1 = Pin() diff --git a/src/Electrical/Analog/sensors.jl b/src/Electrical/Analog/sensors.jl index abad6fa43..ec3fe3ae2 100644 --- a/src/Electrical/Analog/sensors.jl +++ b/src/Electrical/Analog/sensors.jl @@ -1,7 +1,20 @@ """ - CurrentSensor(; name) +```julia +function CurrentSensor(; name) +``` + +Creates a circuit component that measures the current flowing through it. Analogous to +an ideal ammeter. -Sensor to measure the current through a branch in amperes. +# States +- `i(t)`: [`A`] + Current through the sensor + +# Connectors +- `p` + Positive pin +- `n` + Negative pin """ function CurrentSensor(; name) @named p = Pin() @@ -16,9 +29,19 @@ function CurrentSensor(; name) end """ - PotentialSensor(; name) +```julia +function PotentialSensor(; name) +``` -Sensor to measure the potential in volt. +Creates a circuit component which measures the potential at a pin. + +# States +- `phi(t)`: [`V`] + The potential at this point + +# Connectors +- `p` + Pin at which potential is to be measured """ function PotentialSensor(; name) @named p = Pin() @@ -31,9 +54,22 @@ function PotentialSensor(; name) end """ - VoltageSensor(; name) +```julia +function VoltageSensor(; name) +``` + +Creates a circuit component that measures the voltage across it. Analogous to +an ideal voltmeter. -Sensor to measure the potential difference between two pins in volt. +# States +- `v(t)`: [`V`] + The voltage across this component + +# Connectors +- `p` + Positive pin +- `n` + Negative pin """ function VoltageSensor(; name) @named p = Pin() @@ -48,9 +84,26 @@ function VoltageSensor(; name) end """ - PowerSensor(; name) +```julia +function PowerSensor(; name) +``` + +Combines a [`VoltageSensor`](@ref) and a [`CurrentSensor`](@ref) to measure the power being +consumed by a circuit. + +# States +- `power(t)`: [`W`] + The power being consumed, given by the product of voltage and current. -Sensor to measure the power in watt. +# Connectors +- `pc` + Corresponds to the `p` pin of the [`CurrentSensor`](@ref) +- `nc` + Corresponds to the `n` pin of the [`CurrentSensor`](@ref) +- `pv` + Corresponds to the `p` pin of the [`VoltageSensor`](@ref) +- `nv` + Corresponds to the `n` pin of the [`VoltageSensor`](@ref) """ function PowerSensor(; name) @named pc = Pin() @@ -71,9 +124,27 @@ function PowerSensor(; name) end """ - MultiSensor(; name) +```julia +function MultiSensor(; name) +``` + +Combines a [`VoltageSensor`](@ref) and a [`CurrentSensor`](@ref). + +# States +- `v(t)`: [`V`] + The voltage across the [`VoltageSensor`](@ref) +- `i(t)`: [`A`] + The current across the [`CurrentSensor`](@ref) -Sensor to measure current [A], voltage [V] and power [W]. +# Connectors +- `pc` + Corresponds to the `p` pin of the [`CurrentSensor`](@ref) +- `nc` + Corresponds to the `n` pin of the [`CurrentSensor`](@ref) +- `pv` + Corresponds to the `p` pin of the [`VoltageSensor`](@ref) +- `nv` + Corresponds to the `n` pin of the [`VoltageSensor`](@ref) """ function MultiSensor(; name) @named pc = Pin() diff --git a/src/Electrical/Analog/sources.jl b/src/Electrical/Analog/sources.jl index c68f1c962..87660e88f 100644 --- a/src/Electrical/Analog/sources.jl +++ b/src/Electrical/Analog/sources.jl @@ -17,12 +17,25 @@ _xH(t, δ, tₒ) = (t-tₒ)*(1+((t-tₒ)/sqrt((t-tₒ)^2+δ^2)))/2 @register_symbolic _triangular_wave(t, δ, f, A, st) """ - ConstantVoltage(;name, V = 1.0) +```julia +function ConstantVoltage(; name, V=1.0) +``` -Source for constant voltage, +The source for an ideal constant voltage. + +# States +- `v(t)`: [`V`] + The voltage across this source, given by `p.v - n.v` and is always constant + +# Connectors +- `p` + Positive pin +- `n` + Negative pin # Parameters: -- `V`: [V] Voltage +- `V`: [`V`] + The constant voltage across the terminals of this source """ function ConstantVoltage(;name, V = 1.0) @named oneport = OnePort() @@ -36,16 +49,35 @@ function ConstantVoltage(;name, V = 1.0) end """ - CosineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) - -Generate cosine voltage. - -# Parameters: -- `frequency`: [Hz] Frequency of sine wave -- `amplitude`: [V] Amplitude of sine wave -- `phase`: [rad] Phase of sine wave -- `offset`: [V] Offset of output voltage -- `start_time`: [s] Output `y = offset` for `t < start_time` +```julia +function CosineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, starttime=0.0, phase=0.0) +``` + +A source in which the voltage across its terminals is a cosine function of time. + + +# States +- `v(t)` + The voltage across this source, given by `p.v - n.v` + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Observables +- `offset`: [`V`] + A constant offset added to the voltage output +- `amplitude`: [`V`] + The amplitude of the cosine function +- `frequency`: [`Hz`] + The frequency of the cosine function +- `starttime`: [`s`] + The time at which the source starts functioning. Before this time, the voltage across + its terminals is 0. +- `phase`: [`rad`] + The phase offset of the cosine function """ function CosineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) δ = 0.00001 @@ -67,15 +99,36 @@ function CosineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_ti end """ -Generate damped sine voltage. - -# Parameters: -- `frequency`: [Hz] Frequency of sine wave -- `amplitude`: [V] Amplitude of sine wave -- `damping`: [1/s] Damping coefficient of sine wave -- `phase`: [rad] Phase of sine wave -- `offset`: [V] Offset of output voltage -- `start_time`: [s] Output `y = offset` for `t < start_time` +```julia +function ExpSineVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0, damping=0.0) +``` + +A source in which the voltage across its terminals is a damped sine function of time. + +# States +- `v(t)`: [`V`] + The voltage across this source, given by `p.v - n.v` + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Parameters +- `offset`: [`V`] + A constant offset added to the voltage output +- `amplitude`: [`V`] + The amplitude of the damped sine function +- `frequency`: [`Hz`] + The frequency of the damped sine function +- `start_time`: [`s`] + The time at which the source starts functioning. Before this time, the voltage across + its terminals is `offset`. +- `phase`: [`rad`] + The phase offset of the damped sine function +- `damping_coef`: [`1/s`] + Damping coefficient of the damped sine function """ function ExpSineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0, damping=0.0) δ = 0.00001 @@ -97,15 +150,33 @@ function ExpSineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_t end """ - RampVoltage(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) +```julia +function RampVoltage(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) +``` -Generate ramp voltage. +A source in which the voltage across grows linearly from `offset` to `offset+height` over +the time interval `duration` starting at `start_time` -# Parameters: -- `height`: [V] Height of ramp -- `duration`: [s] Duration of ramp (= 0.0 gives a Step) -- `offset`: [V] Offset of output voltage -- `start_time`: [s] Output `y = offset` for `t < start_time` +# States +- `v(t)`: [`V`] + The voltage across this source, given by `p.v - n.v` + +# Connectors +- `p` + Positive port +- `n` + Negative port + RampVoltage(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) + +# Parameters +- `offset`: [`V`] + A constant offset added to the voltage output +- `start_time`: [`s`] + The time at which the voltage starts growing +- `duration`: [`s`] + The duration of the ramp (`0.0` gives a step) +- `height`: [`V`] + The amount that the voltage grows in the time interval """ function RampVoltage(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) δ = 0.00001 @@ -125,16 +196,36 @@ function RampVoltage(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0 end """ - SineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) - -Generate sine voltage. - -# Parameters: -- `frequency`: [Hz] Frequency of sine wave -- `amplitude`: [V] Amplitude of sine wave -- `phase`: [rad] Phase of sine wave -- `offset`: [V] Offset of output voltage -- `start_time`: [s] Output `y = offset` for `t < start_time` +```julia +function SineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) +``` + +A source in which the voltage across its terminals is a sine function of time. + + + +# States +- `v(t)`: [`V`] + The voltage across this source, given by `p.v - n.v` + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Parameters +- `offset`: [`V`] + A constant offset added to the voltage output +- `amplitude`: [`V`] + The amplitude of the sine function +- `frequency`: [`Hz`] + The frequency of the sine function +- `start_time`: [`s`] + The time at which the source starts functioning. Before this time, the voltage across + its terminals is `offset`. +- `phase`: [`rad`] + The phase offset of the sine function """ function SineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) δ = 0.00001 @@ -156,9 +247,32 @@ function SineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time end """ - SquareVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) - -Generate square voltage. +```julia +function SquareVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) +``` + +A source in which the voltage across its terminals is a square function of time. + +# States +- `v(t)`: [`V`] + The voltage across this source, given by `p.v - n.v` + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Parameters +- `offset`: [`V`] + A constant offset added to the voltage output +- `amplitude`: [`V`] + The amplitude of the square wave function +- `frequency`: [`Hz`] + The frequency of the square wave function +- `start_time`: [`s`] + The time at which the source starts functioning. Before this time, the voltage across + its terminals is `offset`. """ function SquareVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) δ = 0.0001 @@ -178,14 +292,30 @@ function SquareVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_t end """ - StepVoltage(;name, offset=0.0, start_time=0.0, height=1.0) - -Generate step voltage. - -# Parameters: -- `height`: [V] Height of step -- `offset`: [V] Offset of output voltage -- `start_time`: [s] Output `y = offset` for `t < start_time` +```julia +function StepVoltage(;name, offset=0.0, start_time=0.0, height=1.0) +``` + +A source in which the voltage across its terminals increases from `offset` to `offset+height` at +`starttime` + +# States +- `v(t)`: [`V`] + The voltage across this source, given by `p.v - n.v` + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Observables +- `offset`: [`V`] + A constant offset added to the voltage output +- `start_time`: [`s`] + The time at which the source starts functioning, and the voltage jumps +- `height`: [`V`] + Magnitude of increase in voltage """ function StepVoltage(;name, offset=0.0, start_time=0.0, height=1.0) δ = 0.0001 @@ -204,6 +334,34 @@ function StepVoltage(;name, offset=0.0, start_time=0.0, height=1.0) extend(ODESystem(eqs, t, [], pars; name=name), oneport) end +""" +```julia +function TriangularVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) +``` + +A source in which the voltage across its terminals is a triangular function of time. + +# States +- `v(t)`: [`V`] + The voltage across this source, given by `p.v - n.v` + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Observables +- `offset`: [`V`] + A constant offset added to the voltage output +- `amplitude`: [`V`] + Amplitude of the triangular wave function +- `frequency`: [`Hz`] + Frequency of the triangular wave function +- `start_time`: [`s`] + The time at which the source starts functioning. Before this, the output of the source is + `offset` +""" function TriangularVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) δ = 0.00001 diff --git a/src/Electrical/Digital/components.jl b/src/Electrical/Digital/components.jl index 1e40ae607..6ae1b1170 100644 --- a/src/Electrical/Digital/components.jl +++ b/src/Electrical/Digital/components.jl @@ -1,5 +1,25 @@ # Adders +""" +```julia +function HalfAdder(; name) +``` + +Takes two bits as input, and outputs the sum and the carry + +# States +- `sum(t)` + The sum of the input bits +- `carry(t)` + The carry generated by the input bits +# Connectors +- `x1`, `x2` + The two inputs to add +- `y1` + Output [`DigitalPin`](@ref) corresponding to the sum +- `y2` + Output [`DigitalPin`](@ref) corresponding to the carry +""" function HalfAdder(; name) @named x1 = DigitalPin() @named x2 = DigitalPin() @@ -16,6 +36,27 @@ function HalfAdder(; name) ODESystem(eqs, t, [sum, carry], [], systems=[x1, x2, y1, y2], name=name) end +""" +```julia +function FullAdder(; name) +``` + +Takes three bits as input, and outputs the sum and the carry + +# States +- `sum(t)` + The sum of the input bits +- `carry(t)` + The carry generated by the input bits + +# Connectors +- `x1`, `x2`, `x3` + The three inputs to add +- `y1` + Output [`DigitalPin`](@ref) corresponding to the sum +- `y2` + Output [`DigitalPin`](@ref) corresponding to the carry +""" function FullAdder(; name) @named x1 = DigitalPin() @named x2 = DigitalPin() @@ -37,6 +78,24 @@ end # This selects data from the `N` input ports (`d₀` to `dₙ₋₁`) # using values of `n` select lines, where `N = 2^n` +""" +```julia +function MUX(; name, N=4) +``` + +Standard Multiplexer. Selects data from `N` input ports using the values +of `n` select lines, where `N=2ⁿ`. For the `i`th input port to be selected, +the values of the select lines should correspond to the binary representation +of `i`. + +# Connectors +- `d1`, `d2`, ... + The `N` input lines +- `s1`, `s2`, ... + The `n` select lines +- `y` + The output, selected from one of the `N` input lines +""" function MUX(; name, N=4) n = log2(N) try n = Int(n) catch(e) throw("`N` must be a power of 2") end @@ -68,6 +127,25 @@ end # This selects one of the `N` output ports (`y₀` to `yₙ₋₁`) # to transmit data `d` using values of `n` select lines, where `N = 2^n` +""" +```julia +function DEMUX(; name, N=4) +``` + +Standard Demultiplexer. Performs the reverse operation of a [`MUX`](@ref). +Selects one of the `N` output ports to transmit the input `d` using the +values of `n` select lines, where `N=2ⁿ`. For the `i`th output port to be +selected, the values of the select lines should correspond to the binary +representation of `i`. + +# Connectors +- `d` + The input to be transmitted to one of the output lines +- `s1`, `s2`, ... + The `n` select lines +- `y1`, `y2`, ... + The `N` output lines +""" function DEMUX(; name, N=4) n = log2(N) try n = Int(n) catch(e) throw("`N` must be a power of 2") end @@ -96,6 +174,20 @@ end # Encoder-Decoder # Encodes `N` inputs to `n` outputs, where `N = 2^n` +""" +```julia +function Encoder(; name, N=4) +``` + +Encodes `N` inputs to `n` outputs, where `N=2ⁿ`. Exactly one of the inputs should be `1`. +If the `i`th input is `1`, then the output corresponds to the binary representation of `i`. + +# Connectors +- `d1`, `d2`, ... + The `N` input lines +- `y1`, `y2`, ... + The `n` output lines +""" function Encoder(; name, N=4) n = log2(N) try n = Int(n) catch(e) throw("`N` must be a power of 2") end @@ -132,6 +224,21 @@ function Encoder(; name, N=4) end # Decodes `n` inputs to `N` outputs, where `N = 2^n` +""" +```julia +function Decoder(; name, n=2) +``` + +Performs the reverse operation of an [`Encoder`](@ref). Decodes `n` inputs +to `N` outputs, where `N=2ⁿ`. The `i`th output is `1` if the values of +the select lines correspond to the binary representation of `1`. + +# Connectors +- `d1`, `d2`, ... + The `n` input lines +- `y1`, `y2`, ... + The `N` output lines +""" function Decoder(; name, n=2) N = 2^n d = map(0:n-1) do i diff --git a/src/Electrical/Digital/gates.jl b/src/Electrical/Digital/gates.jl index 9d69d6291..ef480138a 100644 --- a/src/Electrical/Digital/gates.jl +++ b/src/Electrical/Digital/gates.jl @@ -1,3 +1,16 @@ +""" +```julia +function Not(; name) +``` + +NOT gate in 9-level logic. + +# Connectors +- `x` + Input [`DigitalPin`](@ref) +- `y` + Output [`DigitalPin`](@ref) +""" function Not(; name) @named x = DigitalPin() @named y = DigitalPin() @@ -9,6 +22,19 @@ function Not(; name) ODESystem(eqs, t, [], [], systems=[x, y], name=name) end +""" +```julia +function And(; name, N=2) +``` + +AND gate in 9-level logic, with `N` inputs + +# Connectors +- `x1`, `x2`, ... + `N` input [`DigitalPin`](@ref)s +- `y` + Output [`DigitalPin`](@ref) +""" function And(; name, N=2) x = map(1:N) do i DigitalPin(name=Symbol(:x, i)) @@ -23,6 +49,19 @@ function And(; name, N=2) ODESystem(eqs, t, [], [], systems=[x..., y], name=name) end +""" +```julia +function Nand(; name, N=2) +``` + +NAND gate in 9-level logic, with `N` inputs + +# Connectors +- `x1`, `x2`, ... + `N` input [`DigitalPin`](@ref)s +- `y` + Output [`DigitalPin`](@ref) +""" function Nand(; name, N=2) x = map(1:N) do i DigitalPin(name=Symbol(:x, i)) @@ -37,6 +76,19 @@ function Nand(; name, N=2) ODESystem(eqs, t, [], [], systems=[x..., y], name=name) end +""" +```julia +function Or(; name, N=2) +``` + +OR gate in 9-level logic, with `N` inputs + +# Connectors +- `x1`, `x2`, ... + `N` input [`DigitalPin`](@ref)s +- `y` + Output [`DigitalPin`](@ref) +""" function Or(; name, N=2) x = map(1:N) do i DigitalPin(name=Symbol(:x, i)) @@ -51,6 +103,19 @@ function Or(; name, N=2) ODESystem(eqs, t, [], [], systems=[x..., y], name=name) end +""" +```julia +function Nor(; name, N=2) +``` + +NOR gate in 9-level logic, with `N` inputs + +# Connectors +- `x1`, `x2`, ... + `N` input [`DigitalPin`](@ref)s +- `y` + Output [`DigitalPin`](@ref) +""" function Nor(; name, N=2) x = map(1:N) do i DigitalPin(name=Symbol(:x, i)) @@ -65,6 +130,19 @@ function Nor(; name, N=2) ODESystem(eqs, t, [], [], systems=[x..., y], name=name) end +""" +```julia +function Xor(; name, N=2) +``` + +XOR gate in 9-level logic, with `N` inputs + +# Connectors +- `x1`, `x2`, ... + `N` input [`DigitalPin`](@ref)s +- `y` + Output [`DigitalPin`](@ref) +""" function Xor(; name, N=2) x = map(1:N) do i DigitalPin(name=Symbol(:x, i)) @@ -79,6 +157,19 @@ function Xor(; name, N=2) ODESystem(eqs, t, [], [], systems=[x..., y], name=name) end +""" +```julia +function Xnor(; name, N=2) +``` + +XNOR gate in 9-level logic, with `N` inputs + +# Connectors +- `x1`, `x2`, ... + `N` input [`DigitalPin`](@ref)s +- `y` + Output [`DigitalPin`](@ref) +""" function Xnor(; name, N=2) x = map(1:N) do i DigitalPin(name=Symbol(:x, i)) diff --git a/src/Electrical/Digital/sources.jl b/src/Electrical/Digital/sources.jl index 5b25c7e2c..fe5383cc1 100644 --- a/src/Electrical/Digital/sources.jl +++ b/src/Electrical/Digital/sources.jl @@ -1,3 +1,16 @@ +""" +```julia +function PulseDiff(; name, Val=1, dt=0.1) +``` + +# States +- `val(t)` + Output value of the source + +# Connectors +- `d` + Output [`DigitalPin`](@ref) +""" function PulseDiff(; name, Val=1, dt=0.1) @named d = DigitalPin() @variables val(t) @@ -11,6 +24,17 @@ function PulseDiff(; name, Val=1, dt=0.1) ODESystem(eqs, t, [val], [], systems=[d], defaults=Dict(Val=>0), name=name) end +""" +```julia +function Set(; name) +``` + +Source that outputs a constant signal of `1`. + +# Connectors +- `d` + Output [`DigitalPin`](@ref) +""" function Set(; name) @named d = DigitalPin() @@ -20,6 +44,17 @@ function Set(; name) ODESystem(eqs, t, [], [], systems=[d], name=name) end +""" +```julia +function Reset(; name) +``` + +Source that outputs a constant signal of `1` + +# Connectors +- `d` + Output [`DigitalPin`](@ref) +""" function Reset(; name) @named d = DigitalPin() @@ -29,6 +64,17 @@ function Reset(; name) ODESystem(eqs, t, [], [], systems=[d], name=name) end +""" +```julia +function Pulse(; name, duty_cycle=0.5, T=1.0) +``` + +Pulse output with specified `duty_cycle` and time period (`T`) + +# Connectors +- `d` + Output [`DigitalPin`](@ref) +""" function Pulse(; name, duty_cycle=0.5, T=1.0) @named d = DigitalPin() diff --git a/src/Electrical/utils.jl b/src/Electrical/utils.jl index 0a1f655b0..d6932cfd1 100644 --- a/src/Electrical/utils.jl +++ b/src/Electrical/utils.jl @@ -5,16 +5,32 @@ end ODESystem(Equation[], t, sts, [], name=name, defaults=Dict(v=>1.0, i=>1.0)) end -Base.@doc "Port for an electrical system." Pin +@doc """ +```julia +@connector function Pin(; name) +``` + +A pin in an analog circuit. + +# States +- `v(t)`: [`V`] + The voltage at this pin +- `i(t)`: [`A`] + The current passing through this pin +""" Pin """ - OnePort(;name, v_start=0.0, i_start=0.0) +```julia + OnePort(; name, v_start=0.0, i_start=0.0) +``` -Component with two electrical pins p and n and current i from p to n. +Component with two electrical pins `p` and `n` and current `i` from `p` to `n`. # Parameters: -- `v_start`: [V] Initial voltage across the component -- `i_start`: [A] Initial current through the component +- `v_start`: [`V`] + Initial voltage across the component +- `i_start`: [`A`] + Initial current through the component """ function OnePort(;name, v_start=0.0, i_start=0.0) @named p = Pin() @@ -39,4 +55,17 @@ end ] ODESystem(Equation[], t, [val, v, i], [], defaults=Dict(val=>0, i=>0), name=name) end +@doc """ +```julia +@connector function DigitalPin(; name) +``` + +A pin in a digital circuit. + +# States +- `v(t)`: [`V`] The voltage at this pin +- `i(t)`: [`A`] The current passing through this pin +- `val(t)`: The binary value of the pin at this point. A voltage from `0V` to `0.8V` is a binary value + of `0`. A voltage in the range `2.0V` to `5.0V` is `1`. Any other value is `X`. +""" DigitalPin From f4c3cd21f295d7959107328a002af525bb5b915a Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Thu, 28 Apr 2022 23:11:20 +0530 Subject: [PATCH 2/3] Add docstrings to docs --- docs/src/API/electrical.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/src/API/electrical.md b/docs/src/API/electrical.md index b57f30995..1db7eb2a0 100644 --- a/docs/src/API/electrical.md +++ b/docs/src/API/electrical.md @@ -8,15 +8,16 @@ CurrentModule = ModelingToolkitStandardLibrary.Electrical ```@docs Pin OnePort +DigitalPin ``` ## Analog Components ```@docs -Capacitor Ground -Inductor Resistor +Capacitor +Inductor IdealOpAmp ``` @@ -30,7 +31,7 @@ PowerSensor MultiSensor ``` -## Analogue Sources +## Analog Sources ```@docs ConstantVoltage @@ -49,4 +50,33 @@ SquareCurrent TriangularCurrent CosineCurrent ExpSineCurrent +``` + +## Digital Gates +```@docs +Not +And +Nand +Or +Nor +Xor +Xnor +``` + +## Digital Components +```@docs +HalfAdder +FullAdder +MUX +DEMUX +Encoder +Decoder +``` + +## Digital Sources +```@docs +PulseDiff +Set +Reset +Pulse ``` \ No newline at end of file From f74f1d4079d99f58b91dcace90d087500baa7937 Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Thu, 28 Apr 2022 23:27:08 +0530 Subject: [PATCH 3/3] Add docstrings for current sources --- src/Electrical/Analog/sources.jl | 255 +++++++++++++++++++++++++------ 1 file changed, 207 insertions(+), 48 deletions(-) diff --git a/src/Electrical/Analog/sources.jl b/src/Electrical/Analog/sources.jl index 87660e88f..791c3b9ad 100644 --- a/src/Electrical/Analog/sources.jl +++ b/src/Electrical/Analog/sources.jl @@ -50,14 +50,14 @@ end """ ```julia -function CosineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, starttime=0.0, phase=0.0) +function CosineVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, starttime=0.0, phase=0.0) ``` A source in which the voltage across its terminals is a cosine function of time. # States -- `v(t)` +- `v(t)`: [`V`] The voltage across this source, given by `p.v - n.v` # Connectors @@ -151,7 +151,7 @@ end """ ```julia -function RampVoltage(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) +function RampVoltage(; name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) ``` A source in which the voltage across grows linearly from `offset` to `offset+height` over @@ -166,7 +166,6 @@ the time interval `duration` starting at `start_time` Positive port - `n` Negative port - RampVoltage(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) # Parameters - `offset`: [`V`] @@ -197,7 +196,7 @@ end """ ```julia -function SineVoltage(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) +function SineVoltage(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) ``` A source in which the voltage across its terminals is a sine function of time. @@ -293,11 +292,11 @@ end """ ```julia -function StepVoltage(;name, offset=0.0, start_time=0.0, height=1.0) +function StepVoltage(; name, offset=0.0, start_time=0.0, height=1.0) ``` A source in which the voltage across its terminals increases from `offset` to `offset+height` at -`starttime` +`start_time` # States - `v(t)`: [`V`] @@ -382,12 +381,25 @@ end # Current Sources ###################################################################################################### """ - ConstantCurrent(;name, I = 1.0) +```julia +function ConstantCurrent(; name, I = 1.0) +``` + +The source for an ideal constant current. -Source for constant current. +# States +- `i(t)`: [`A`] + The current through this source, which is always constant + +# Connectors +- `p` + Positive pin +- `n` + Negative pin # Parameters: -- `I`: [A] Current +- `I`: [`A`] + The constant current through the terminals of this source """ function ConstantCurrent(;name, I = 1.0) @named oneport = OnePort() @@ -401,16 +413,35 @@ function ConstantCurrent(;name, I = 1.0) end """ - CosineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) +```julia +function CosineCurrent(; name, offset=0.0, amplitude=1.0, frequency=1.0, starttime=0.0, phase=0.0) +``` -Generate cosine current. +A source in which the current through its terminals is a cosine function of time. -# Parameters: -- `frequency`: [Hz] Frequency of sine wave -- `amplitude`: [A] Amplitude of sine wave -- `phase`: [rad] Phase of sine wave -- `offset`: [A] Offset of output current -- `start_time`: [s] Output `y = offset` for `t < start_time` + +# States +- `i(t)`: [`A`] + The current through this source + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Observables +- `offset`: [`A`] + A constant offset added to the current output +- `amplitude`: [`A`] + The amplitude of the cosine function +- `frequency`: [`Hz`] + The frequency of the cosine function +- `starttime`: [`s`] + The time at which the source starts functioning. Before this time, the current through + its terminals is 0. +- `phase`: [`rad`] + The phase offset of the cosine function """ function CosineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) δ = 0.00001 @@ -432,17 +463,36 @@ function CosineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_ti end """ - ExpSineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0, damping=0.0) +```julia +function ExpSineCurrent(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0, damping=0.0) +``` -Generate damped sine current. +A source in which the current through its terminals is a damped sine function of time. -# Parameters: -- `frequency`: [Hz] Frequency of sine wave -- `amplitude`: [A] Amplitude of sine wave -- `damping`: [1/s] Damping coefficient of sine wave -- `phase`: [rad] Phase of sine wave -- `offset`: [A] Offset of output current -- `start_time`: [s] Output `y = offset` for `t < start_time` +# States +- `i(t)`: [`A`] + The current through this source + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Parameters +- `offset`: [`A`] + A constant offset added to the current output +- `amplitude`: [`A`] + The amplitude of the damped sine function +- `frequency`: [`Hz`] + The frequency of the damped sine function +- `start_time`: [`s`] + The time at which the source starts functioning. Before this time, the current through + its terminals is `offset`. +- `phase`: [`rad`] + The phase offset of the damped sine function +- `damping_coef`: [`1/s`] + Damping coefficient of the damped sine function """ function ExpSineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0, damping=0.0) δ = 0.00001 @@ -464,15 +514,32 @@ function ExpSineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_t end """ - RampCurrent(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) +```julia +function RampCurrent(; name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) +``` -Generate ramp current. +A source in which the current grows linearly from `offset` to `offset+height` over +the time interval `duration` starting at `start_time` -# Parameters: -- `height`: [A] Height of ramp -- `duration`: [s] Duration of ramp (= 0.0 gives a Step) -- `offset`: [A] Offset of output current -- `start_time`: [s] Output `y = offset` for `t < start_time` +# States +- `i(t)`: [`A`] + The current through this source + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Parameters +- `offset`: [`A`] + A constant offset added to the current output +- `start_time`: [`s`] + The time at which the current starts growing +- `duration`: [`s`] + The duration of the ramp (`0.0` gives a step) +- `height`: [`A`] + The amount that the current grows in the time interval """ function RampCurrent(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0) δ = 0.00001 @@ -492,16 +559,36 @@ function RampCurrent(;name, offset=0.0, start_time=0.0, duration=1.0, height=1.0 end """ - SineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) +```julia +function SineCurrent(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) +``` -Generate sine current. +A source in which the current through its terminals is a sine function of time. -# Parameters: -- `frequency`: [Hz] Frequency of sine wave -- `amplitude`: [A] Amplitude of sine wave -- `phase`: [rad] Phase of sine wave -- `offset`: [A] Offset of output current -- `start_time`: [s] Output `y = offset` for `t < start_time` + + +# States +- `i(t)`: [`A`] + The current through this source + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Parameters +- `offset`: [`A`] + A constant offset added to the current output +- `amplitude`: [`V`] + The amplitude of the sine function +- `frequency`: [`Hz`] + The frequency of the sine function +- `start_time`: [`s`] + The time at which the source starts functioning. Before this time, the current through + its terminals is `offset`. +- `phase`: [`rad`] + The phase offset of the sine function """ function SineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0, phase=0.0) δ = 0.00001 @@ -522,6 +609,34 @@ function SineCurrent(;name, offset=0.0, amplitude=1.0, frequency=1.0, start_time extend(ODESystem(eqs, t, [], pars; name=name), oneport) end +""" +```julia +function SquareCurrent(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) +``` + +A source in which the current through its terminals is a square function of time. + +# States +- `i(t)`: [`A`] + The current through this source + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Parameters +- `offset`: [`A`] + A constant offset added to the current output +- `amplitude`: [`A`] + The amplitude of the square wave function +- `frequency`: [`Hz`] + The frequency of the square wave function +- `start_time`: [`s`] + The time at which the source starts functioning. Before this time, the current through + its terminals is `offset`. +""" function SquareCurrent(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) δ = 0.0001 @@ -540,14 +655,30 @@ function SquareCurrent(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_t end """ - StepCurrent(;name, offset=0.0, start_time=0.0, height=1.0) +```julia +function StepCurrent(; name, offset=0.0, start_time=0.0, height=1.0) +``` -Generate step current. +A source in which the current through its terminals increases from `offset` to `offset+height` at +`start_time` -# Parameters: -- `height`: [A] Height of step -- `offset`: [A] Offset of output current -- `start_time`: [s] Output `y = offset` for `t < start_time` +# States +- `i(t)`: [`A`] + The current through this source + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Observables +- `offset`: [`A`] + A constant offset added to the current output +- `start_time`: [`s`] + The time at which the source starts functioning, and the current jumps +- `height`: [`A`] + Magnitude of increase in current """ function StepCurrent(;name, offset=0.0, start_time=0.0, height=1.0) δ = 0.0001 @@ -566,6 +697,34 @@ function StepCurrent(;name, offset=0.0, start_time=0.0, height=1.0) extend(ODESystem(eqs, t, [], pars; name=name), oneport) end +""" +```julia +function TriangularCurrent(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) +``` + +A source in which the current through its terminals is a triangular function of time. + +# States +- `i(t)`: [`A`] + The current through this source + +# Connectors +- `p` + Positive port +- `n` + Negative port + +# Observables +- `offset`: [`A`] + A constant offset added to the current output +- `amplitude`: [`A`] + Amplitude of the triangular wave function +- `frequency`: [`Hz`] + Frequency of the triangular wave function +- `start_time`: [`s`] + The time at which the source starts functioning. Before this, the output of the source is + `offset` +""" function TriangularCurrent(; name, offset=0.0, amplitude=1.0, frequency=1.0, start_time=0.0) δ = 0.00001