Struct nicompiler_backend::instruction::Instruction

pub struct Instruction {
    pub instr_type: InstrType,
    pub args: InstrArgs,
}

Struct for a general instruction, consisting of type and arguments.

Different instruction types expects different fields in their argument dictionary. Behavior for minimally expected keys are defined in Instruction::new, behavior of default values are defined in Instruction::eval_inplace.

Implemented instruction types and their expected fields:

1. InstrType::CONST:
   • const
2. InstrType::SINE:
   • freq
   • amplitude: Default is 1.0
   • offset: Default is 0.0
   • phase: Default is 0.0

Fields

instr_type: InstrType

args: InstrArgs

Implementations

impl Instruction

pub fn new(instr_type: InstrType, args: InstrArgs) -> Self

Constructs an Instruction object.

This method serves as the foundational constructor upon which custom constructor wrappers for new instructions should be built. For each instruction type, it ensures that the args dictionary contains the required keys.

Missing keys will cause a panic.

Examples

Constructing a new CONST instruction (this is effectively the underlying implementation for Instruction::new_const, the more convenient constructor):

use nicompiler_backend::instruction::*;
use std::collections::HashMap;

let mut const_args = InstrArgs::new();
const_args.insert("value".to_string(), 1.0);
let const_instr = Instruction::new(InstrType::CONST, const_args);

If you fail to provide the required argument fields, it will panic:

let mut const_args = InstrArgs::new();
let const_instr = Instruction::new(InstrType::CONST, const_args);

The panic message will be: thread 'main' panicked at 'Expected instr type CONST to contain key value'.

Constructing a new SINE instruction:

let mut sine_args = InstrArgs::new();
sine_args.insert("freq".to_string(), 10.0);
sine_args.insert("offset".to_string(), 1.0); // amplitude and phase will use default values
let sine_instr = Instruction::new(InstrType::SINE, sine_args);

pub fn eval_inplace(&self, t_arr: &mut ArrayViewMut1<'_, f64>)

Evaluates the instruction and populates the given array view with float-point values.

This method takes a mutable array view (t_arr) and modifies its values in-place based on the instruction type and its arguments.

• For InstrType::CONST, the array will be filled with the constant value specified by the value argument.
• For InstrType::SINE, a sinusoidal waveform is generated using the arguments freq, amplitude, offset, and phase. Default values are used if certain arguments are not provided.

Arguments

• t_arr - A mutable 1D array view that will be populated with the evaluated values.

Examples

Given an instruction set with a constant and a sine instruction, and an array representing time values from 0 to 1:

use ndarray::{Array2, Array1};
use nicompiler_backend::instruction::*;

let t_row = ndarray::Array1::linspace(0.0, 1.0, 10);
let mut t_values = ndarray::stack(ndarray::Axis(0), &[t_row.view(), t_row.view()]).unwrap();
// Use wrappers to create sine and constant instructions same as the examples above
let const_instr = Instruction::new_const(1.0);
const_instr.eval_inplace(&mut t_values.row_mut(0));

let sine_instr = Instruction::new_sine(10.0, None, None, Some(1.0));
sine_instr.eval_inplace(&mut t_values.row_mut(1));
assert!(t_values[[0, 0]] == 1. && t_values[[0, 1]] == 1.);

pub fn new_const(value: f64) -> Instruction

Wrapper for conveniently creating new constant instructions. Example usage equivalent to the constant example above:

let const_instr = Instruction::new_const(1.0);

pub fn new_sine( freq: f64, amplitude: Option<f64>, phase: Option<f64>, dc_offset: Option<f64> ) -> Instruction

Constructs a new sine instruction with provided parameters.

Allows for convenient creation of sine instructions by specifying the frequency and optionally, amplitude, phase, and DC offset. Unspecified parameters will not be included in the instruction’s argument dictionary, allowing for default values to be used elsewhere if necessary.

Arguments

• freq: The frequency of the sine wave.
• amplitude: Optional amplitude of the sine wave. If None, it will not be set in the instruction.
• phase: Optional phase offset of the sine wave in radians. If None, it will not be set in the instruction.
• dc_offset: Optional DC offset for the sine wave. If None, it will not be set in the instruction.

Examples

Constructing a sine instruction with a specified frequency, and DC offset. Amplitude and phase will use any default values defined elsewhere:

---

use nicompiler_backend::instruction::*;

let sine_instr = Instruction::new_sine(10.0, None, None, Some(1.0));

Trait Implementations

impl Clone for Instruction

fn clone(&self) -> Instruction

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Display for Instruction

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<Instruction> for Instruction

fn eq(&self, other: &Instruction) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Instruction