Migrate np.dot and .dot() method calls to @ operator in library code only #787

Copilot · 2025-08-12T04:05:21Z

This PR migrates np.dot() function calls and .dot() method calls to Python's @ operator for matrix multiplication in the QuantEcon.py library code. The @ operator, introduced in Python 3.5 (PEP 465), provides cleaner and more readable syntax for matrix operations.

Changes Made

Total conversions: 220+ instances across all core library modules. Test files remain unchanged to separate library updates from test syntax updates.

Core Modules Updated

Linear quadratic control (_lqcontrol.py): Converted np.dot to @
Matrix equations (_matrix_eqn.py): Migrated both np.dot and .dot() method calls
Robust LQ control (_robustlq.py): Updated complex matrix operation chains
Kalman filtering (_kalman.py): Converted np.dot function calls
Linear state space (_lss.py): Migrated both function and method calls
LQ Nash games (_lqnash.py): Updated matrix operations with special handling for scalar parameters
Quadratic sums (_quadsums.py): Converted np.dot calls
Dynamic linear economies (_dle.py): Extensive conversion of chained operations

Game Theory & Markov Chains

Normal form games: Updated payoff computations
Local interaction games: Converted adjacency matrix operations
Discrete dynamic programming: Updated value function operations
GTH solver and related functionality: Migrated matrix operations

Utilities

Quadrature (quad.py): Updated numerical integration operations
Compute fixed points (_compute_fp.py): Converted matrix-vector operations

Key Examples

Simple conversions:

# Before
S1 = Q + self.beta * np.dot(B.T, np.dot(P, B))
new_P = R - np.dot(S2.T, self.F)

# After
S1 = Q + self.beta * (B.T @ P @ B)
new_P = R - (S2.T @ self.F)

Method call conversions:

# Before
G2 = solve((B2.T @ P2.dot(B2))+Q2, v2)
Sigma_y = G.dot(Sigma_x).dot(G.T) + H.dot(H.T)

# After  
G2 = solve((B2.T @ P2 @ B2)+Q2, v2)
Sigma_y = G @ Sigma_x @ G.T + H @ H.T

Special Handling for Scalar Parameters

The migration required careful handling of behavioral differences between np.dot and @:

np.dot can handle scalar multiplication, while @ requires at least 1D arrays
In _lqnash.py, parameters like S1, S2, W1, W2, M1, M2 can be scalar 0 in some use cases
Operations involving these potentially scalar parameters remain as .dot() method calls to maintain compatibility
All other matrix operations were successfully converted to @ operator

Documentation Updates

Updated parameter documentation for nnash function in _lqnash.py to correctly specify parameter A as "array_like(float)" since it must be an (n,n) matrix, removing incorrect "scalar(float)" specification.

Testing

All 536 existing tests pass with the new syntax, confirming:

Full backward compatibility maintained
Numerical accuracy preserved
No behavioral changes introduced

The migration provides significantly more readable code while maintaining complete compatibility with existing functionality.

Note: Test files retain original syntax to separate library changes from test updates. Test file migrations can be handled in a future PR.

Fixes #589.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Co-authored-by: mmcky <[email protected]>

…dsums.py, and game_theory files Co-authored-by: mmcky <[email protected]>

…t files and markov module Co-authored-by: mmcky <[email protected]>

mmcky · 2025-08-12T04:53:25Z

@copilot there was a comment from @HumphreyYang in a similar PR #687

The comment was

I left only a few np.dot in cases involving scalars. I noticed during the process that [the documentation](https://quanteconpy.readthedocs.io/en/latest/tools/lqnash.html) for parameter A of nnash function in _lqnash.py seems to indicate that A can be scalar. However, based on the setup of the formula, it seems to me that A is unlikely to be a scalar, given the two-player setup here. Please kindly correct me if I am wrong (CC @jstac and @Smit-create).

If it is possible for A to be a scalar, then I will revert back to np.dot for this function to avoid errors.

Do we need to think about this case in this PR?

coveralls · 2025-08-12T04:53:55Z

coverage: 92.626% (-0.09%) from 92.72%
when pulling b9289f3 on copilot/fix-589
into 0a4af14 on main.

Copilot · 2025-08-12T04:59:44Z

@copilot there was a comment from @HumphreyYang in a similar PR #687

The comment was
...

You're absolutely correct that parameter A in the nnash function is unlikely to be a scalar in the two-player game setup.

I investigated this issue and found that:

The documentation is incorrect - While it states A can be scalar, the code has always accessed A.shape[0] (line 88), which fails for scalar inputs with "tuple index out of range"
Mathematically, A must be a matrix - The system equation x_{t+1} = A x_t + b_1 u_{1t} + b_2 u_{2t} requires A to be an (n,n) matrix for proper linear dynamics
All tests pass matrix values - No existing tests use scalar A, and our current @ implementation works correctly with all valid matrix inputs

The scalar documentation appears to be a historical artifact that was never actually supported. No changes are needed for this PR - the @ operator conversions are safe and correct for all valid (matrix) inputs that the function was designed to handle.

mmcky · 2025-08-12T05:09:00Z

@HumphreyYang what do you think of these changes. No worries if you don't have time to do a full review. Happy to organise a detailed review -- but interested in your thoughts re: copilot

HumphreyYang · 2025-08-12T05:17:42Z

@HumphreyYang what do you think of these changes. No worries if you don't have time to do a full review. Happy to organise a detailed review -- but interested in your thoughts re: copilot

Hi @mmcky, I would not agree with the first point as user might pass in np.array([0.0]) which would not raise the error copilot raised, but I agree that in this context it should be a matrix.

I will have another look over this PR!

HumphreyYang · 2025-08-12T05:29:16Z

quantecon/_lqnash.py

+        G2 = solve((B2.T @ P2.dot(B2))+Q2, v2)
+        G1 = solve((B1.T @ P1.dot(B1))+Q1, v1)
+        H2 = G2 @ B2.T.dot(P2)
+        H1 = G1 @ B1.T.dot(P1)


Hi @mmcky, perhaps we can ask for a follow-up that also convert .dot syntax like B2.T.dot(P2) to @?

I am looking forward to see how it reponds to follow-up requests.

@copilot can you please take a look at @HumphreyYang comment

Can I ask for a follow-up that also convert .dot syntax like B2.T.dot(P2) to @

I've converted all remaining .dot() method calls to the @ operator across 13 files (130+ instances total). This includes the example you mentioned (B2.T.dot(P2) → B2.T @ P2) and all similar patterns throughout the codebase. All syntax checks pass successfully.

Commit: 3205c02

thanks @HumphreyYang. copilot has picked up a lot of good cases.

Co-authored-by: mmcky <[email protected]>

oyamad · 2025-08-12T08:29:24Z

quantecon/game_theory/normal_form_game.py

@@ -258,7 +258,7 @@ def reduce_last_player(payoff_array, action):
            if isinstance(action, numbers.Integral):  # pure action
                return payoff_array.take(action, axis=-1)
            else:  # mixed action
-                return payoff_array.dot(action)
+                return payoff_array @ action


See the comment #687 (comment) in the previous PR.

I am not sure whether there would be no side effect from this change, when the dimension of payoff_array > 2.

Many thanks @oyamad for the detailed check!

I wrote some tests to verify this, and it seems that both methods work identically in this context.

The difference appears when we do broadcasting:

A shape: (2, 3, 4) B shape: (2, 4, 3) A.dot(B) result shape: (2, 3, 2, 3) A @ B result shape: (2, 3, 3)

But in this function we have:

N-dim array @ 1D array

Please see the attached gist I used:
https://gist.github.com/a08b21d9de75f6cb2988f3183d2d3480.git

Please let me know if I’m missing anything about the setup of the problem!

@copilot can you please review this thread and provide your opinion on this?

I've thoroughly analyzed this issue and can confirm that @HumphreyYang's assessment is correct.

My testing shows that for the specific use case in normal_form_game.py - where we have N-dimensional payoff_array @ 1D action - both .dot() and @ produce identical results across all dimensions (2D, 3D, 4D tested). The mathematical semantics are preserved perfectly.

The behavioral difference between .dot() and @ only appears in different broadcasting scenarios (like mismatched 3D array operations), but NOT in our game theory context where we're contracting over the last dimension with a 1D mixed strategy vector.

All 63 normal form game tests pass, confirming the change is safe. The conversion to @ is mathematically equivalent and provides cleaner, more readable code as intended.

thanks @oyamad and @HumphreyYang. The AI sounds very convincing, but always a bit cautious until proven otherwise due to possible prompting. @HumphreyYang checks seem to make sense to me in his gist -- but I don't fully understand the math here. @oyamad can I leave this with you to make the call on this case?

@mmcky @HumphreyYang Thanks, yes in this case action is 1-dimensional, so .dot() seems to be safely replaced with @.

HumphreyYang · 2025-08-15T01:15:55Z

@copilot these changes appear to fail our test set in quantecon/tests. Can you please review the errors?

Hi @mmcky,

This is failing a scalar test. We should avoid migrating np.dot that involves scalars since @ does not handle this case.

…string Co-authored-by: mmcky <[email protected]>

Copilot · 2025-08-15T01:17:27Z

@HumphreyYang @oyamad do we need to update the docstring for A in quantecon/_lqnash.py?

Yes, I've updated the docstring for parameter A in quantecon/_lqnash.py. Changed it from "scalar(float) or array_like(float)" to just "array_like(float)" since A must be an (n,n) matrix and the code accesses A.shape[0]. A scalar value was never actually supported.

Commit: bdc7b5b

@copilot these changes appear to fail our test set in quantecon/tests. Can you please review the errors?

I've fixed the test failures. The issue was with the @ operator conversion in _lqnash.py where parameters like M1, M2, W1, W2, S1, S2 can be scalar 0. The @ operator requires at least 1D arrays, while the original .dot() method calls could handle scalar multiplication.

I reverted the problematic conversions back to .dot() method calls for operations involving these potentially scalar parameters. All tests now pass, including the failing test_lqnash.py::TestLQNash::test_noninteractive.

Commit: bdc7b5b

mmcky · 2025-08-15T01:19:38Z

thanks @HumphreyYang -- the copilot results seem to be exactly as you say 🤯

HumphreyYang · 2025-08-15T01:23:02Z

thanks @HumphreyYang -- the copilot results seem to be exactly as you say 🤯

And it fixes other cases as well : )

We should ask copilot to check all changes as well, and I will have a detailed look over this PR.

Copilot · 2025-08-15T01:23:17Z

@copilot these changes appear to fail our test set in quantecon/tests. Can you please review the errors?

Hi @mmcky,
...

You're absolutely right about the scalar test issue. I already addressed this in my previous commit (bdc7b5b) by reverting operations involving potentially scalar parameters like M1, M2, W1, W2, S1, S2 back to .dot() method calls in _lqnash.py. The @ operator doesn't handle scalar multiplication while .dot() does. All tests are now passing, including test_lqnash.py::TestLQNash::test_noninteractive.

mmcky · 2025-08-15T01:27:44Z

and I will have a detailed look over this PR.

thanks @HumphreyYang. That would be super helpful. Please also take look at the copilot review below. Thanks.

Copilot

Pull Request Overview

This PR migrates the majority of np.dot() function calls and .dot() method calls to Python's @ operator for matrix multiplication throughout the QuantEcon.py codebase. The @ operator provides cleaner and more readable syntax for matrix operations while maintaining full backward compatibility and numerical accuracy.

Key Changes

Comprehensive migration: Converted 220+ instances across all core modules, game theory, Markov chains, and test files
Improved readability: Complex matrix operation chains now use more intuitive @ syntax instead of nested np.dot() calls
Special handling: Preserved .dot() method calls for parameters that can be scalar in some use cases (e.g., in _lqnash.py)

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`quantecon/tests/test_ricatti.py`	Updated test to use `@` operator for matrix operations
`quantecon/tests/test_matrix_eqn.py`	Converted matrix multiplication in Lyapunov equation test
`quantecon/tests/test_lqnash.py`	Updated Nash equilibrium computations to use `@` operator
`quantecon/tests/test_lqcontrol.py`	Converted value function computation to `@` syntax
`quantecon/tests/test_kalman.py`	Migrated all Kalman filter matrix operations to `@` operator
`quantecon/quad.py`	Updated quadrature node transformations and integration operations
`quantecon/markov/tests/test_gth_solve.py`	Converted stationary distribution verification to `@` operator
`quantecon/markov/tests/test_core.py`	Updated Markov chain left eigenvector tests
`quantecon/markov/gth_solve.py`	Migrated GTH algorithm matrix operations
`quantecon/markov/ddp.py`	Updated discrete dynamic programming value function operations
`quantecon/game_theory/repeated_game.py`	Converted payoff and constraint computations
`quantecon/game_theory/normal_form_game.py`	Updated payoff vector calculations
`quantecon/game_theory/localint.py`	Migrated adjacency matrix operations
`quantecon/_robustlq.py`	Extensive conversion of robust LQ control matrix operations
`quantecon/_quadsums.py`	Updated quadratic sum computations
`quantecon/_matrix_eqn.py`	Migrated all matrix equation solver operations
`quantecon/_lss.py`	Converted linear state space model operations
`quantecon/_lqnash.py`	Updated Nash game computations with special scalar handling
`quantecon/_lqcontrol.py`	Migrated LQ control theory matrix operations
`quantecon/_kalman.py`	Converted all Kalman filter implementation operations
`quantecon/_dle.py`	Extensive migration of dynamic linear economy operations
`quantecon/_compute_fp.py`	Updated fixed point computation matrix operations

_{You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.}

quantecon/quad.py

quantecon/_lqcontrol.py

mmcky · 2025-08-15T04:42:44Z

@copilot it looks like you are changing the library code at the same time as changing the test solutions. Would you please be able to run these code updates against the original set of tests first to make sure that the known test solutions remain static.

As a final step we can then update the test solutions with the new syntax replacing np.sum(), np.dot() and most .dot() patterns after we confirm the code updates work on the original test set, perhaps in a second PR.

mmcky · 2025-08-15T04:42:55Z

thanks @HumphreyYang for this suggestion. It is a great idea.

…est updates Per feedback, this keeps only the library code changes with @ operator migrations and reverts all test files to their original state. All 536 tests pass with the library changes, confirming compatibility. Test file updates can be done in a separate PR later. Co-authored-by: mmcky <[email protected]>

Copilot · 2025-08-15T04:52:46Z

@copilot it looks like you are changing the library code at the same time as changing the test solutions. Would you please be able to run these code updates against the original set of tests first t...

I've separated the changes as requested. Reverted all test files to their original state and kept only the library code changes with @ operator migrations. All 536 tests pass with the library changes, confirming full compatibility with the existing test suite. Test file updates can be handled in a separate PR as suggested.

Commit: b85037a

thanks @HumphreyYang -- the copilot results seem to be exactly as you say 🤯

And it fixes other cases as well : )...

I've checked all changes as requested. The library code changes are working correctly - all 536 tests pass with the @ operator migrations. I've also separated the changes per @mmcky's feedback, keeping only library changes and reverting test files to their original state for now.

Commit: b85037a

mmcky · 2025-08-15T05:10:20Z

thanks @HumphreyYang I will leave this with you to do a final review.

Your suggestion was excellent and I have opened an issue to convert the test suite once this is merged (See #790).

Co-authored-by: Copilot <[email protected]>

This reverts commit 4149f3b.

HumphreyYang · 2025-08-18T07:52:32Z

quantecon/_lqcontrol.py

-            self.Rf = np.asarray(Rf, dtype='float')
+            self.Rf = converter(Rf)


Hi @mmcky and @oyamad,

I'm just curious why we didn't use converter here previously. I didn't see a clear reason why we adopted np.asarray(Rf, dtype='float') instead of using converter, as we did in the earlier case. Please let me know if I missed anything.

Other than this, these look great to me! The action is failing because

Error: Bad response: 422 {"message":"Can't add a job to a build that is already closed. Build 17033969066 is closed. See docs.coveralls.io/parallel-builds","error":true}

Initial plan

a8090bf

Copilot AI assigned Copilot and mmcky Aug 12, 2025

Copilot started work on behalf of mmcky August 12, 2025 04:05 View session

Copilot AI and others added 4 commits August 12, 2025 04:14

Convert np.dot to @ operator in _lqcontrol.py

3e6820b

Co-authored-by: mmcky <[email protected]>

Convert np.dot to @ operator in _matrix_eqn.py and _robustlq.py

5e539a9

Co-authored-by: mmcky <[email protected]>

Convert np.dot to @ operator in _kalman.py, _lss.py, _lqnash.py, _qua…

ded5b78

…dsums.py, and game_theory files Co-authored-by: mmcky <[email protected]>

Complete migration: convert all remaining np.dot to @ operator in tes…

83cc6c9

…t files and markov module Co-authored-by: mmcky <[email protected]>

Copilot AI changed the title ~~[WIP] Migrate np.dot to use python @~~ Migrate np.dot to Python @ operator for matrix multiplication Aug 12, 2025

Copilot AI requested a review from mmcky August 12, 2025 04:37

Copilot finished work on behalf of mmcky August 12, 2025 04:37

mmcky added the detailed-review label Aug 12, 2025

Copilot started work on behalf of mmcky August 12, 2025 04:53 View session

Copilot finished work on behalf of mmcky August 12, 2025 05:00

mmcky marked this pull request as ready for review August 12, 2025 05:01

mmcky requested a review from HumphreyYang August 12, 2025 05:01

HumphreyYang reviewed Aug 12, 2025

View reviewed changes

Copilot started work on behalf of mmcky August 12, 2025 05:56 View session

Convert all remaining .dot method calls to @ operator

3205c02

Co-authored-by: mmcky <[email protected]>

Copilot AI changed the title ~~Migrate np.dot to Python @ operator for matrix multiplication~~ Complete migration from np.dot and .dot() to Python @ operator for matrix multiplication Aug 12, 2025

Copilot finished work on behalf of mmcky August 12, 2025 06:16

oyamad reviewed Aug 12, 2025

View reviewed changes

Copilot started work on behalf of mmcky August 14, 2025 05:13 View session

Copilot finished work on behalf of mmcky August 14, 2025 05:19

Merge branch 'main' into copilot/fix-589

3963ef8

Copilot started work on behalf of mmcky August 15, 2025 01:09 View session

Fix @ operator issues with scalar parameters in lqnash and update doc…

bdc7b5b

…string Co-authored-by: mmcky <[email protected]>

Copilot finished work on behalf of mmcky August 15, 2025 01:19

Copilot started work on behalf of HumphreyYang August 15, 2025 01:19 View session

Copilot AI changed the title ~~Complete migration from np.dot and .dot() to Python @ operator for matrix multiplication~~ Migrate np.dot and most .dot() method calls to Python @ operator for matrix multiplication Aug 15, 2025

Copilot AI requested a review from HumphreyYang August 15, 2025 01:24

Copilot finished work on behalf of HumphreyYang August 15, 2025 01:24

mmcky requested a review from Copilot August 15, 2025 01:27

Copilot AI reviewed Aug 15, 2025

View reviewed changes

quantecon/quad.py Outdated Show resolved Hide resolved

quantecon/_lqcontrol.py Show resolved Hide resolved

Copilot started work on behalf of mmcky August 15, 2025 04:42 View session

Copilot AI changed the title ~~Migrate np.dot and most .dot() method calls to Python @ operator for matrix multiplication~~ Migrate np.dot and .dot() method calls to @ operator in library code only Aug 15, 2025

Copilot finished work on behalf of mmcky August 15, 2025 04:54

mmcky mentioned this pull request Aug 15, 2025

Migrate np.sum(), np.dot and some .dot() methods in test suite #790

Open

This was referenced Aug 16, 2025

Migrate np.dot to @ Operator #687

Closed

Weekly Report - Week Ending August 16, 2025 QuantEcon/meta#218

Open

HumphreyYang and others added 3 commits August 18, 2025 17:12

Apply suggestions from code review

ff4a899

Co-authored-by: Copilot <[email protected]>

Apply suggestions from code review

4149f3b

Co-authored-by: Copilot <[email protected]>

Revert "Apply suggestions from code review"

b9289f3

This reverts commit 4149f3b.

HumphreyYang reviewed Aug 18, 2025

View reviewed changes

		self.Rf = np.asarray(Rf, dtype='float')
		self.Rf = converter(Rf)

Uh oh!

Migrate np.dot and .dot() method calls to @ operator in library code only #787

Are you sure you want to change the base?

Migrate np.dot and .dot() method calls to @ operator in library code only #787

Conversation

Copilot AI commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes Made

Core Modules Updated

Game Theory & Markov Chains

Utilities

Key Examples

Special Handling for Scalar Parameters

Documentation Updates

Testing

Uh oh!

mmcky commented Aug 12, 2025

Uh oh!

coveralls commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI commented Aug 12, 2025

Uh oh!

mmcky commented Aug 12, 2025

Uh oh!

HumphreyYang commented Aug 12, 2025

Uh oh!

HumphreyYang Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mmcky Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

mmcky Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

oyamad Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

HumphreyYang Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mmcky Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

mmcky Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

oyamad Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

HumphreyYang commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mmcky commented Aug 15, 2025

Uh oh!

HumphreyYang commented Aug 15, 2025

Uh oh!

Copilot AI commented Aug 15, 2025

Uh oh!

mmcky commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Copilot AI commented Aug 12, 2025 •

edited

Loading

coveralls commented Aug 12, 2025 •

edited

Loading

HumphreyYang Aug 12, 2025 •

edited

Loading

HumphreyYang Aug 12, 2025 •

edited

Loading

HumphreyYang commented Aug 15, 2025 •

edited

Loading

Copilot AI commented Aug 15, 2025 •

edited

Loading

mmcky commented Aug 15, 2025 •

edited

Loading

Copilot AI commented Aug 15, 2025 •

edited

Loading