NDArray Library (Java)

Small NumPy-inspired Java library for ndarray operations, developed as a DevOps team project.

Authors: see AUTHORS.

Repository: https://github.com/sMouaad/DevOps-Project

Documentation & API Reference

Project Goals

• Build a clean ndarray API in Java for float data.
• Apply collaborative Git workflow with feature branches and PR reviews.
• Keep test quality high and track coverage in CI.
• Deliver a clear project report in this README.

Features Implemented

• 1D ndarray core with metadata (ndim, shape, size).
• 2D ndarray support with matrix validation.
• Creation helpers: array, zeros, arange.
• Addition operations: add and addInPlace with strict shape checks.
• Optional extensions: scalar addition and sum() reduction.
• reshape(int... shape) with size consistency validation.
• NumPy-like string display for 1D arrays (including ellipsis for large arrays).
• Defensive copy behavior on constructors and exports.

Usage Examples

NdArray a = NdArray.array(new float[] {1f, 2f, 3f});
NdArray b = NdArray.zeros(3);
NdArray c = NdArray.arange(0f, 6f, 2f);

NdArray m = NdArray.array(new float[][] {{1f, 2f}, {3f, 4f}});
NdArray sum = m.add(NdArray.array(new float[][] {{10f, 10f}, {10f, 10f}}));
NdArray reshaped = NdArray.arange(6f).reshape(2, 3);
NdArray shifted = a.add(10f);
float total = shifted.sum();

Tech Stack and Tooling Choices

• Java 17: stable LTS runtime for modern Java features.
• Maven: standard build/test lifecycle and dependency management.
• JUnit 5: clear unit test structure and assertions.
• JaCoCo: code coverage report integrated with Maven.
• GitHub + GitHub Actions: PR-centered collaboration and CI automation.

Git Workflow and PR Validation

Workflow used by the team:

• No direct pushes to main.
• Work is done in feature branches.
• Every meaningful change goes through PR review.
• CI must pass before merge.
• We use GitHub Issues to plan work and assign tasks to each teammate.

Feature branches used during the project:

• feature/ndarray-core-1d
• feature/array-zeros-arange
• feature/addition-ops
• feature/reshape
• feature/ndarray-2d
• feature/ci-coverage
• feature/print-display
• feature/optional-ndarray-extensions
• feature/sonarqube-integration
• feature/docker
• feature/maven-dist
• feature/iac-ansible-terraform
• feature/readme-report

PR validation checklist:

• Local tests pass (mvn test or mvn verify).
• New behavior is covered by tests.
• Reviewer leaves comments/approval.
• CI is green before merge.

CI/CD

Current CI setup:

• GitHub Actions workflow runs mvn verify on push/PR.
• Test and build verification are mandatory in CI.
• JaCoCo coverage artifacts are uploaded from target/site/jacoco/.
• SonarQube analysis is triggered in the same workflow using repository secrets (SONAR_HOST_URL and SONAR_TOKEN).
• SonarQube is configured to wait for the quality gate result.
• SNAPSHOT publishing: On every push to main, if tests pass, a SNAPSHOT artifact is published to GitHub Packages.
• Publishing is blocked if line coverage drops below 70%.

Using the SNAPSHOT

Published package coordinates:

<dependency>
    <groupId>org.sadisamir</groupId>
    <artifactId>ndarray-library</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

Add the package registry to your pom.xml:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/sMouaad/DevOps-Project</url>
    </repository>
</repositories>

Publishing workflow summary:

• runs only on pushes to main
• runs mvn verify before deploy
• deploys with Maven deploy to GitHub Packages
• keeps the project version on *-SNAPSHOT for now

Docker

A demo container is available that showcases all NDArray features on startup.

Quick Start (Pull and Run)

docker run --rm ghcr.io/smouaad/devops-project:main

Build Locally

# Build the image
docker build -t ndarray-demo .

# Run the demo
docker run --rm ndarray-demo

Image Tags

Images are published to GitHub Container Registry (ghcr.io/smouaad/devops-project):

Tag	Description
main	Latest build from main branch
<version>	Semantic version (e.g., 1.0.0, 1.0)
<sha>	Specific commit SHA

CI/CD Pipeline

The Docker workflow (.github/workflows/docker.yml):

• Builds on every push to main and version tags (v*)
• Validates builds on pull requests (no push)
• Uses multi-stage build for minimal image size
• Caches layers with GitHub Actions cache

Cloud Deployment

We use Terraform + Ansible to deploy the container to GCP. Spins up a free-tier e2-micro VM with Docker.

cd infrastructure/scripts
./setup-gcp.sh    # one-time setup
./deploy.sh       # creates VM and deploys container
./destroy.sh      # tear down when done

See infrastructure/README.md for details.

Delivered Scope

Mandatory:

• 1D and 2D ndarray support.
• Creation functions (array, zeros, arange).
• Addition operations (add, addInPlace).
• Reshape with validation.
• NumPy-like display.

Optional / bonus (difficulty level in brackets):

• Scalar addition and sum() reduction — library extensions.
• Maven SNAPSHOT publishing to GitHub Packages, gated by 70% coverage [2].
• Multi-stage Docker image published to GHCR with semver/sha tags [3].
• Infrastructure as Code (Terraform + Ansible) for GCP deployment [4].
• SonarQube static analysis integrated in CI with quality gate [3].
• CI/coverage badges and GitHub Pages documentation site [1].

Feedback

This project was a good learning experience for us. We learned that having a working pipeline early saves a lot of time later, and we learned how the use tools such as terraform & ansible along the way.

What went well:

• CI + tests helped us avoid regressions.
• Small PRs made reviews easier.
• Docker made demo execution consistent across machines.
• Terraform + Ansible split infra creation and app deployment clearly.

What was harder:

• Covering edge cases (2D behavior, reshape validation) with clean tests.
• Keeping feature branches up to date with main.
• Initial cloud setup (credentials, IAM roles, SSH keys).

What we can improve next:

• Add moretests (edgecases) for 2D operations
• Add an automatic changelog for releases.
• Add a PR template...