rspice 0.1.0

Pure-Rust circuit simulation backend
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

use crate::BasicComponent;
use crate::ComponentRef;
use crate::ConnectionRef;
use crate::EquationRef;
use crate::NetRef;
use crate::RspiceError;
use crate::TransientMatrix;
use crate::TransientResult;
use crate::TransientVector;

/// Electronic circuit, containing a number of connected basic components.
///
/// Each component is connected to a number of nets, which are
/// directly connected regions of wire.
pub struct Circuit {
    n_nets: usize,
    n_components: usize,
    n_connections: usize,
    // basic component, list of connected nets, index of first connection
    components: Vec<(Box<dyn BasicComponent>, Vec<usize>, usize)>,
    // connection indices for each net
    nets: Vec<Vec<usize>>,
}

impl Circuit {
    /// Create a new empty circuit.
    pub fn new() -> Self {
        Self {
            n_nets: 0,
            n_components: 0,
            n_connections: 0,
            components: Vec::new(),
            nets: Vec::new(),
        }
    }

    /// Create a new unconnected net and return a reference to it.
    pub fn createNet(&mut self) -> NetRef {
        let index = self.n_nets;
        self.n_nets += 1;
        self.nets.push(Vec::new());
        NetRef { index: index }
    }

    /// Create a new basic component and connect it to a list of nets.
    ///
    /// This method is only provided to implement new basic components,
    /// which should call it in their `create()` method.
    /// Any circuit or compound component should use the corresponding `create()` methods
    /// instead, to make sure that the correct number of nets is passed.
    ///
    /// See [BasicComponent] for more information.
    pub fn createBasicComponent(
        &mut self,
        mut component: Box<dyn BasicComponent>,
        nets: Vec<NetRef>,
    ) -> ComponentRef {
        self.n_components += 1;
        let mut raw_nets = Vec::new();
        let mut connections = Vec::new();
        let mut raw_connections = Vec::new();
        let mut equations = Vec::new();
        let first_connection = self.n_connections;
        for net in &nets {
            raw_nets.push(net.index);
            connections.push(ConnectionRef {
                index: self.n_connections,
            });
            raw_connections.push(self.n_connections);
            equations.push(EquationRef {
                index: self.n_connections * 2,
            });
            equations.push(EquationRef {
                index: self.n_connections * 2 + 1,
            });
            self.nets[net.index].push(self.n_connections);
            self.n_connections += 1;
        }
        component.initCircuit(nets, connections, equations);
        self.components
            .push((component, raw_nets, first_connection));
        ComponentRef {
            connections: raw_connections,
        }
    }

    /// Perform a transient simulation.
    ///
    /// Will run steps of `step` seconds, up to `duration` seconds.
    pub fn performTransientAnalysis(
        &mut self,
        duration: f64,
        step: f64,
    ) -> Result<TransientResult, RspiceError> {
        // create empty matrix
        let mut matrix = TransientMatrix::new(self.n_nets, self.n_connections);

        // each net gets two equations of its own
        for net in 0..self.n_nets {
            // all currents going into the net must add up to zero
            for connection in &self.nets[net] {
                *matrix.raw_current_term(net * 2, *connection) = 1.0;
            }

            // all currents' derivatives must also add up to zero
            for connection in &self.nets[net] {
                *matrix.raw_current_derivative_term(net * 2 + 1, *connection) = 1.0;
            }
        }

        // each component initializes its own equations
        for component in &mut self.components {
            component.0.initTransient(&mut matrix);
        }

        let mut result = Vec::new();

        // transient loop
        let mut t = 0.0;
        loop {
            // TODO: non-linear components
            // solve linear equation
            let result_at_t = matrix.solve()?;
            result.push(result_at_t.clone());
            if t >= duration {
                break;
            }
            // let all components update their equations
            let wrapped_result = TransientVector::new(result_at_t.into(), self.n_nets);
            for component in &mut self.components {
                component
                    .0
                    .updateTransient(&mut matrix, &wrapped_result, t, step);
            }
            t += step;
        }

        // generate result
        let mut result_components = Vec::new();
        for component in &self.components {
            result_components.push((component.1.clone(), component.2));
        }
        Ok(TransientResult {
            values_over_time: result,
            step: step,
            n_nets: self.n_nets,
            components: result_components,
        })
    }
}