{"id":13805010,"url":"https://github.com/vbrusca/ZigMatrixUtils","last_synced_at":"2025-05-13T18:33:19.703Z","repository":{"id":227655832,"uuid":"772043015","full_name":"vbrusca/ZigMatrixUtils","owner":"vbrusca","description":"A matrix utility library written in Zig. Provides functions and tools for manipulating matrices and solving linear algebra problems. A great source for leaning about the Zig programming language.","archived":false,"fork":false,"pushed_at":"2024-09-20T15:46:26.000Z","size":65913,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-18T21:46:53.213Z","etag":null,"topics":["matrices","matrix","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vbrusca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-14T12:32:39.000Z","updated_at":"2024-09-20T15:45:41.000Z","dependencies_parsed_at":"2024-05-29T17:56:01.950Z","dependency_job_id":"277d6440-c60e-44c8-a93c-15273ebf2827","html_url":"https://github.com/vbrusca/ZigMatrixUtils","commit_stats":null,"previous_names":["vbrusca/zigmatrixutils"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrusca%2FZigMatrixUtils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrusca%2FZigMatrixUtils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrusca%2FZigMatrixUtils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrusca%2FZigMatrixUtils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vbrusca","download_url":"https://codeload.github.com/vbrusca/ZigMatrixUtils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254003502,"owners_count":21997897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["matrices","matrix","zig"],"created_at":"2024-08-04T01:00:56.327Z","updated_at":"2025-05-13T18:33:14.691Z","avatar_url":"https://github.com/vbrusca.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zig Matrix Utils\nAn open source matrix utility library written in Zig.\nThe full Zig project is included in this repo.\n\n## Zig Build Version\nThis project was built against Zig version \"zig-windows-x86_64-0.12.0\".\n\n## Developers\nVictor Brusca\u003cbr\u003e\nCarlo Bruscani\n\n## Documentation\nI'll provide a viewable but not 100% usable link to the Zig Matrix Utils documentation here. Links don't work but you can browse the functions and their signature. For proper use clone or download the repo and view the documentation site locally.\n\u003cbr\u003e\n[Zig Generated API Docs](https://htmlpreview.github.io/?https://github.com/vbrusca/ZigMatrixUtils/blob/main/docs/index.html)\n\n## Source Material\nThis project was built using the following books as a basis.\u003cbr\u003e\n1. Elementary Linear Algebra by Larson, Edwards\n2. Mathematics for 3D Game Programming and Computer Graphics 3rd Edition by Eric Lengyel\n\n## Project Goals\nHaving worked on this project solo for a while I've almost reached my initial goal of porting the main body of material over to the Zig programming language.\nAfter the completion of chapter 6's material I'm going to switch gears for a little while and work on another coding project. This library will receive long-term updates\nin the interim period.\n\n01. LT: Continuous development to complete the material regarding linear algebra and matrix manipulations.\u003cbr\u003e\n02. LT: Normalize the use of const across all slice based function arguments, refine function arguments.\n03. LT: To keep the project up to date with new versions of Zig as the language matures.\n04. LT: To complete and refine the code documentation.\n06. ST: Version 0.64 - 0.65: Complete base material for chapter 6 including the remaining sections 6.4 and 6.5.\n08. ST: Add execution time tracking to the remaining theorem, problem, and unit tests.\n09. ST: To complete all missing function documentation, unit tests, and extended tests.\n10. LT: Revisit the project and apply needed material for chapter 7.\n\n## Running Unit Tests\nYou can run the full set of unit tests from inside the project with the following command.\u003cbr\u003e\n\u003cpre\u003e\nzig test ./src/main.zig\n\u003c/pre\u003e\nThere are over 350 test run to verify functionality. Feel free to think of them as demonstrations of the associated functions. You can also capture the test output with the following command on DOS terminals. You'll have to search around and find an equivalent command if you are on MacOS, Linux, or Unix for your respective shell.\n\u003cpre\u003e\nzig test ./src/main.zig \u003e all_test_output.txt 2\u003e\u00261\n\u003c/pre\u003e\nCurrently the library sets each module to use fast floating point math. This has already shown a positive impact in the performance of different functions in the function execution time list. If there is some instability in floating point math just comment out this line in the header of main.zig and XmtxUtils.zig.\n\u003cpre\u003e\ncomptime {\n    @setFloatMode(std.builtin.FloatMode.optimized); //Optimized);\n}\n\u003c/pre\u003e\n\n## Project Build Commands\nHow to build an exe (NOT USED). There is no real main code for this library currently.\n\u003cpre\u003e\nzig build-exe -femit-docs ./src/main.zig -O ReleaseSmall -fstrip -fsingle-threaded -femit-bin=\"zig-out/bin/main.exe\"\n\u003c/pre\u003e\n\nHow to build a static library.\n\u003cpre\u003e\nzig build-lib -femit-docs ./src/XmtxUtils.zig -O ReleaseSmall -fstrip -fsingle-threaded -femit-bin=\"zig-out/lib/XmtxUtils.lib\"\n\u003c/pre\u003e\n\nHow to build an object.\n\u003cpre\u003e\nzig build-obj -femit-docs ./src/XmtxUtils.zig -O ReleaseSmall -fstrip -fsingle-threaded -femit-bin=\"zig-out/lib/XmtxUtils.obj\"\n\u003c/pre\u003e\n\nHow to build a dynamic library.\n\u003cpre\u003e\nzig build-lib -femit-docs ./src/XmtxUtils.zig -lc -dynamic -isystem -fstrip -fsingle-threaded -femit-bin=\"zig-out/lib/XmtxUtils.dll\"\n\u003c/pre\u003e\n\n## Guides\n\nYou can look into specific use cases for the library in the \"Guides\" section.\n**Please note that the guides may be slightly out of sync with regard to the latest version of the library as it develops. Those gaps will be closed periodically over time and as a better way of tracking the guides associated with code changes evolves. The guides associate library functions with vector and matrix actions etc. You can use them as a loose example of how to use the library. For more complex and comprehensive use cases check the unit tests for theorems, examples, and problems from the basis text books.\n\n[Guides](https://github.com/vbrusca/ZigMatrixUtils/tree/main/guides)\n\n## Rough Example of Usage\n\u003cpre\u003e\ntest \"XMTX: MF3D - Lengyel: Theorem 3.21 test\" {\n    prntNl();\n    //Let F be an n X n matrix and let the entries of n X n matrix G be defined as\n    //Gij = Cji(F) * (1 / detF)\n    //where Cji(F) is the cofactor of (F^Tij) then G = F^-1\n    //Gij = Cij(F^T) * (1 / detF)\n\n    //Cij(H) = (-1)^(i + j)detH\n    std.debug.print(\"Test 1:\\n\", .{});\n    const alloc: std.mem.Allocator = std.testing.allocator;\n    var F: [4]f32 = .{ 5, 6, 8, 9 };\n    var invF: [4]f32 = .{ 0, 0, 0, 0 };\n    var cols: usize = 2;\n\n    std.debug.print(\"F Matrix:\\n\", .{});\n    clnXmtx(\u0026F);\n    prntXmtx(\u0026F, cols);\n\n    const detF = try detXmtx(\u0026F, cols, \u0026alloc, 0);\n    std.debug.print(\"detF = {}\\n\", .{detF});\n\n    F = .{ 5, 6, 8, 9 };\n    var idtF: [4]f32 = .{ 1, 0, 0, 1 };\n    var sclr: f32 = 0.0;\n    var b: bool = rdcXmtxInl(\u0026F, cols, false, true, \u0026idtF, 2, false, \u0026sclr);\n    try std.testing.expectEqual(true, b);\n\n    std.debug.print(\"Calculated inverse F (should be identity matrix):\\n\", .{});\n    clnXmtx(\u0026F);\n    prntXmtx(\u0026F, cols);\n    try std.testing.expectEqual(true, isIdtXmtx(\u0026F, cols));\n\n    std.debug.print(\"Calculated inverse F (should be inverse matrix):\\n\", .{});\n    clnXmtx(\u0026idtF);\n    prntXmtx(\u0026idtF, cols);\n\n    F = .{ 5, 6, 8, 9 };\n    b = getInvFromDet2(\u0026F, detF, \u0026invF);\n    try std.testing.expectEqual(true, b);\n\n    std.debug.print(\"Generated inverse from detF (should be inverse matrix):\\n\", .{});\n    clnXmtx(\u0026invF);\n    prntXmtx(\u0026invF, cols);\n    try std.testing.expectEqual(true, equXmtx(\u0026idtF, \u0026invF));\n\n    std.debug.print(\"Test 2:\\n\", .{});\n    var F2: [9]f32 = .{ 2, 3, 8, 6, 0, -3, -1, 3, 2 };\n    var invF2: [9]f32 = .{ 0, 0, 0, 0, 0, 0, 0, 0, 0 };\n    cols = 3;\n\n    std.debug.print(\"F2 Matrix:\\n\", .{});\n    clnXmtx(\u0026F2);\n    prntXmtx(\u0026F2, cols);\n\n    const detF2 = try detXmtx(\u0026F2, cols, \u0026alloc, 0);\n    std.debug.print(\"detF2 = {}\\n\", .{detF2});\n\n    F2 = .{ 2, 3, 8, 6, 0, -3, -1, 3, 2 };\n    var idtF2: [9]f32 = .{ 1, 0, 0, 0, 1, 0, 0, 0, 1 };\n    sclr = 0.0;\n    b = rdcXmtxInl(\u0026F2, cols, false, true, \u0026idtF2, 3, false, \u0026sclr);\n    try std.testing.expectEqual(true, b);\n\n    std.debug.print(\"Calculated inverse F2 (should be identity matrix):\\n\", .{});\n    clnXmtx(\u0026F2);\n    prntXmtx(\u0026F2, cols);\n    try std.testing.expectEqual(true, isIdtXmtx(\u0026F2, cols));\n\n    std.debug.print(\"Calculated inverse F2 (should be inverse matrix):\\n\", .{});\n    clnXmtx(\u0026idtF2);\n    prntXmtx(\u0026idtF2, cols);\n\n    F2 = .{ 2, 3, 8, 6, 0, -3, -1, 3, 2 };\n    b = getInvFromDet3(\u0026F2, detF2, \u0026invF2);\n    try std.testing.expectEqual(true, b);\n\n    std.debug.print(\"Generated inverse from detF2 (should be inverse matrix):\\n\", .{});\n    clnXmtx(\u0026invF2);\n    prntXmtx(\u0026invF2, cols);\n    try std.testing.expectEqual(true, equXmtx(\u0026idtF2, \u0026invF2));\n}\n\u003c/pre\u003e\n\n## Execution Times\n\nExecution times are calculated after the last unit test that uses them. You can find the execution time summary in the test output by searching for the term \"Function Execution Times List\". An example of the execution time summary list is shown below.\n\n\u003cpre\u003e\nFunction Execution Times List:\n absF32:\tCount: 1.0e+00\tAvg: 0.000ms 200.000ns\n absF32Ref:\tCount: 1.0e+00\tAvg: 0.000ms 100.000ns\n absF32Ret:\tCount: 1.0e+00\tAvg: 0.000ms 100.000ns\n absXmtx:\tCount: 2.0e+00\tAvg: 0.000ms 300.000ns\n addSclMulXmtxRows:\tCount: 1.0e+00\tAvg: 0.001ms 500.000ns\n addSclMulXmtxRowsInl:\tCount: 1.0e+00\tAvg: 0.000ms 200.000ns\n addSclXmtxRows:\tCount: 1.0e+00\tAvg: 0.000ms 300.000ns\n addSclXmtxRowsInl:\tCount: 1.0e+00\tAvg: 0.005ms 4900.000ns\n addXvec:\tCount: 1.0e+00\tAvg: 0.000ms 200.000ns\n adjXmtx3:\tCount: 1.0e+00\tAvg: 0.012ms 12200.000ns\n adjXmtx4:\tCount: 1.0e+00\tAvg: 0.013ms 12600.000ns\n aglBtwnXvec:\tCount: 1.0e+00\tAvg: 0.009ms 9400.000ns\n altXmtxRows:\tCount: 1.0e+00\tAvg: 0.001ms 500.000ns\n ...\n\u003c/pre\u003e\n\nYou can see the function name, the usage count, and the average execution time in ms and ns. To effectively turn off this memory allocation set \u003cb\u003eMAX_EXEC_TIMES\u003c/b\u003e equal to 1. It is only used by the unit test code, no library functions have execution time monitoring.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvbrusca%2FZigMatrixUtils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvbrusca%2FZigMatrixUtils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvbrusca%2FZigMatrixUtils/lists"}