These two lines seem mutually incompatible.

The idea is that the underlying implementation would beFixedPoint(i_or_f_width, f_width = None, /, *, signed), but I found it clearer to express it like that. Consider how you can dorange(stop) andrange(start, stop).

Makes sense. I wasn't sure if it was that or a typo. Does the first constructor add a sign bit whensigned is true, and otherwise create a number whose range spans from 0 to some value below 1?

Yes, although the exact semantics wrt. the sign bit depends on which Q notation we settle on.

The dominant notation in the industry, at least in the audio ASIC world, is to include the sign bit in the number of integer bits. For example, -1 to 1 is represented as a Q1.23. That would be my vote.

@samimia-swks would you happen to have some references we can cite to show that this is the dominant Q notation in the audio ASIC world? It will be useful evidence that may be worth appending to the RFC document itself.

Bikeshed:lib.fixed,lib.fixnum.

I would lean towardlib.fixed

lib.fixed seems good, looking through the usage and discussion;fixed.Shape,fixed.Value are pretty natural to write.

What is the semantics of this operation?

I just updated it to.cast(shape, f_width=0) locally. The idea is to determinei_width automatically, soFixedPoint.cast(unsigned(8)) would result inUQ(8) andFixedPoint.cast(unsigned(8), f_width = 4) would result inUQ(4, 4).

WhyUQ(4,4)?

FixedPoint.cast() is a building block forFixedPointValue.cast(). The idea is to be able to say «here's a value with n fractional bits, please turn it into an appropriately sizedFixedPointValue». Anunsigned(8) with four fractional bits would have four integer bits left and thus cast toUQ(4, 4).

This API seems confusing and difficult to use. Should we expose it at all?

Decimal support as well?

And probablyFraction as well.

I feel like thei_width andf_width names are difficult enough to read that it's of more importance than bikeshedding to come up with something more readable.

.int_bits,.frac_bits?

cursed option:int, frac = x.width?

+1 onint_bits,frac_bits...

I understand Q-notation is an established one, however since Amaranth defaults to unsigned, I feel that havingSQ andUQ (without having justQ) would serve Amaranth better.

What happens if you assign 1024 to a Q8.8 value?

Signal(Q(8, 8)).eq(1024) would effectively beSignal(signed(17)).eq(1024 << 8). (Orsigned(16) depending on Q notation.)

Speaking of overflow, I figure fixed point overflow should behave like regular integer overflow. Saturating math feels orthogonal to this RFC and could be added through a later RFC that handles both integer and fixed point values.

OK, this is a compelling argument for support of floats. I am convinced that it is a good idea to have floats supported in at least some way. But we need to be very careful around overflows.

I wonder if we could leave it unspecified and implementation-defined until we can get a numerics expert to chime in.

In most DSP applications, simple truncating is done (bit picking, which is equivalent to a floor()) because it's free. I would vote for that being the default behavior at least.

Truncating can also be a big foot gun in some DSP applications that is hard to track down, you can end up with a DC spur that grows over time or over your pipeline with no obvious explanation. A middle ground is round towards zero or symmetrically towards positive/negative infinity (this is nearly free on the output of Xilinx DSP48E1/2 and I believe cheap/free on ECP5 and friends DSPs). The way I personally would handle it would be to make the rounding mode part offixed.Shape type making itfixed.Shape(i_width, f_width, /, *, signed, rounding_mode). Truncate is still a reasonable default for most applications though.

Hm, makingrounding_mode part of the signature is a pretty big action, what happens if you add two numbers with differing rounding modes for example?

To be clear the semantics I'm imagining here are if you havea andb andb has more fractional bits thana then when you assigna.eq(b) the rounding mode that is used is that ofa so that downstream DSP modules can enforce a rounding mode on their inputs.

The scenarios where I can imagine what you propose causing issues are (I'm guessing there are more outside the bounds of my imagination)

1. User addsa andb and then.rounds them
2. A user addsa andb and utilizes the result as a port on their module (I believe this is allowed but still learning the language)

Solutions that solve 1. But not two in no particular order:

1. Don't actually resolve the round until a signal is assigned to something with a concrete value (this seems like a bad idea and probably doesn't solve the problem)
2. Make the rounding mode undefined and require an explicit rounding mode to.round, but this doesn't solve the problem of getting a top level port with an undefined rounding mode

Solutions that I believe would solve both:

1. Choose the rounding mode of the left term
2. Choose the less footgunny rounding mode (TOEVEN,TOODD>SYMZERO,SYMINF>TRUNC) with ties going to either a defined order or the left term
3. Ban arithmetic operations between numbers with different rounding modes and require an explicit cast of one of the arguments with something like.with_mode(other.rounding_mode)
4. Make this undefined behavior and pick one of the above for now

My naive preference inclination would be 3, it seems like a fairly rare scenario and if you end up in it it's probably worth making the user think about what they want the result to be, but I'm not a language designer so take that with a grain of salt

Further thoughts on 3 as an option:

Operations with a constant fixed point value should probably inherit the rounding mode of the non-constant value without requiring an explicit cast because I think the alternative is annoying to deal with (requiring a shape to be passed any time a constant is declared).

I was playing around with this a while back and I no longer think making it a part of the signature is a good idea as there is no platform independent way of providing rounding that infers well in the context of common DSP use cases. My understanding is that that would mean lowering would require adding a new primitive to the AST which doesn't feel like a good strategy. I think a better approach would be to leave rounding and several other common operations that require platform dependent lowering to a subsequent RFC. Currently my biggest stumbling block was that getting reasonable performance required manually instantiating DSPs which meant the design wasn't simulatible in pysim.

This means thatfixed.Shape(7, 0, signed=True) has the same width assigned(8), which seems counterintuitive.

I just managed to hit this myself even though I've read through this a few times

I've thought about this since I wrote the last draft and concluded that this is probably the wrong decision, so I'm intending to change it when I find time to revise the RFC again.

What happens if it's not representable? At least we need to havec.as_float(exact=True) which gives an error in that case.

Agree with this. I would even consider havingexact=True being the default.

This is inconsistent with howConst() works.

This is not addressed yet but will need to be before the next revision.

Is havingi_width positive andf_width negative or the converse in scope for this RFC? If it is then I think.round should takei_width as an optional argument

What would that mean?

Two scenarios where I think you could reasonably end up in this position with the current RFC

1. You start off with say UQ0.16 [0,1) and right shift by 2 the natural representation is still 16 bits but with the range [0, 0.25) and I believe the representation is going to end up being UQ-2.18 in this notation?
2. This is less reasonable but say you throw a 4096 (1<<12) point FFT at values with the format SQ7.10, if you are naive about the scaling and keep the bit width to 18 bits, you end up with SQ19.-2 (ie a step of 4 between every point). This is equivalent in terms of the bits on the wire to starting with SQ0.17 and ending with SQ12.5 but it feels more silly and you can end up there naturally so it should probably be supported

I'm currently working on tracking down some DSP bugs in a project at work that nobody every simulated, in my fixed point emulation code the number format I chose was basically n_bits, exponent which handles these cases more naturally but is probably overall less intelligible. I'd imagine this looking likefixed.Shape(shape, exponent) in amaranth (IEfixed.Shape(signed(18), 2) for SQ19.-2) but that would be a pretty large change I'm not sure it would be a net positive anyways (also don't want to bikeshed here).

Ok I've played with what the implementation does here, this might be a bit long; The implementation does allow the creation of the above types of representations (IE Q-4.20, Q20.-4) and appears to operate on them correctly, however it for the most part won't generate them on its own. Left shift and right shift preserve the number of bits until eitheri_width orf_width would go negative at which point it pads things out:

Right shift works as expected:

In [2]:fixed.SQ(8,8),fixed.SQ(-4,20),Signal(fixed.SQ(8,8))>>8,Signal(fixed.SQ(8,8))>>12Out[2]:(fixed.Shape(8,8,signed=True),fixed.Shape(-4,20,signed=True), (fixedpointSQ0.16 (sig $signal)), (fixedpointSQ0.20 (sig $signal)))

Left shift seems to get converted to unsigned which I think is not the correct behavior:

In [4]:Signal(fixed.SQ(8,8))<<8,Signal(fixed.SQ(8,8))<<9,Signal(fixed.SQ(8,8))<<10,Signal(fixed.SQ(8,8))<<12Out[4]:((fixedpointSQ16.0 (sig $signal)), (fixedpointUQ18.0 (cat (const1'd0) (sig $signal))), (fixedpointUQ19.0 (cat (const2'd0) (sig $signal))), (fixedpointUQ21.0 (cat (const4'd0) (sig $signal))))

I personally think the rounding semantics are a bit difficult to reason about as they stand:

In [5]: (Signal(fixed.SQ(8,8))<<12).round(-4), (Signal(fixed.SQ(8,8))>>12).round(16)Out[5]:((fixedpointUQ21.-4 (+ (slice (cat (const4'd0) (sig $signal)) 4:21) (slice (cat (const 4'd0) (sig $signal))3:4))), (fixedpointSQ0.16 (+ (slice (sig $signal)4:17) (slice (sig $signal)3:4))))

Rounding with negative fractional bits produces the sensible result (wrt signed to unsigned bug), but rounding off the fractional bits in a right shift looses precision when it does not necessarily need too. I think this is a decent argument for either always preserving the number of bits in a (constant) shift, or including ani_width argument to round. Personally I would advocate for always preserving the number of bits because I think that that is easier to reason about and the argument to round can just bewidth noti_width orf_width.

Addition between a number with no fractional bits and one with no integer bits also produces a number 2 bits wider than I believe is necessary:

In [7]:Signal(fixed.SQ(-4,20))+Signal(fixed.SQ(20,-4))Out[7]: (fixedpointSQ22.20 (+ (sig $signal) (cat (const24'd0) (sig $signal))))

would a.max() and.min() method or property make sense here to get a const with the max/min representable value make sense here or is that outside the scope of theShape API given that the base signed and unsigned types don't have that?

We could definitely have additional functionality on specific shapes, e.g. enum shapes are pretty magical, so are layouts..min()/.max() seem completely reasonable to me.

In the implementation at least the semantics of these seem to be different from underlying amaranth values. If the shift amount is an integer these act like.shift_left() and.shift_right(). Those operators should probably be added here and the semantics of__lshift__ and__rshift__ adjusted to match those onunsigned() andsigned().

Note: I may be wrong here, still learning the language

For the comparison operators the rounding behavior seems under defined when the types don't have the same precision, the options seem to be:

1. Round to the precision of the left argument(what the draft implementation does) EDIT: Draft implementation does not have an opinion on this
2. Round to the precision of the least precise argument (easiest for the hardware)
3. Round to the most precise argument (excluding constants maybe?)
4. Ban comparison between values (but maybe not const and value?) with different precision

4. seems bad, I'm going to implement 3 for my FFT testing and see if it ends up being a problem

.as_value() returns a value with a signdedness that doesn't depend on the signdedness of the fixedpoint shape, should there be a.lower() or.numerator() method that returns.as_value() cast to the appropriate signdedness?