Norma.jl

Norma is a Julia prototype for testing algorithms and ideas for coupling and multiphysics, primarily in solid mechanics and heat conduction.

Impact simulation of two bars using different time integrators and mesh types: the left bar uses hexahedral elements with an implicit time integrator; the right bar uses tetrahedral elements with an explicit time integrator. Each subdomain advances independently with its own time step. (~100,000 elements)

Dynamic torsion of a solid cylinder undergoing large deformations. (~160,000 elements)

Large-deformation vibration of a soft rubber ball. The animation plays in real time (100 frames per second) to match simulation time. (~300,000 elements)

---

Quick Start

julia --project=@/path/to/Norma.jl /path/to/Norma.jl/src/Norma.jl input.yaml

Or run it interactively:

using Pkg; Pkg.activate("/path/to/Norma.jl")
using Norma
Norma.run("input.yaml")

---

What is Norma.jl?

• A prototyping framework for multiphysics and coupling algorithms
• Focused on solid mechanics and heat conduction
• Designed for high extensibility and experimentation
• Supports implicit and explicit time integrators

---

Table of Contents

1. Features
2. Installation
3. Running the Code
4. Testing
   • Selective Test Execution
   • Filtering by Name
5. Examples
6. Profiling
7. Debugging
8. Troubleshooting
9. License

---

Features

• Prototyping of coupling and multiphysics algorithms.
• Applications in solid mechanics and heat conduction.
• Designed for extensibility and experimentation.

---

Installation

Clone the Repository

cd /path/to
git clone [email protected]:sandialabs/Norma.jl.git
cd Norma.jl
julia

Set Up the Environment

Within the Julia package manager (enter by pressing ] in the Julia REPL):

pkg> activate .
pkg> registry update
pkg> update
pkg> instantiate

Press Backspace or Delete to exit the package manager.

---

Running the Code

To run the main program, assuming Julia is in your executable path:

julia --project=@/path/to/Norma.jl /path/to/Norma.jl/src/Norma.jl input.yaml

To run Norma interactively from a Julia session:

cd /path/to/Norma.jl
julia
using Pkg
Pkg.activate(".")
using Norma

Then, navigate to your desired example folder and run the simulation. For example:

cd("examples/contact/implicit-dynamic/2-bars")
Norma.run("bars.yaml")

Note: If you make changes to the Norma code, you need to reload the Norma module (using Norma) for those changes to take effect.

Running with Multiple Threads

To run Norma.jl using multiple threads, set the JULIA_NUM_THREADS environment variable before launching Julia. For example, to use 4 threads:

JULIA_NUM_THREADS=4 julia --project=@/path/to/Norma.jl /path/to/Norma.jl/src/Norma.jl input.yaml

Or for interactive usage:

JULIA_NUM_THREADS=4 julia

Inside Julia:

using Pkg
Pkg.activate("/path/to/Norma.jl")
using Norma
Norma.run("input.yaml")

---

Testing

To run the test suite using the Julia REPL:

using Pkg
Pkg.test()

Or from the command line:

cd /path/to/Norma.jl/test
julia --project=@/path/to/Norma.jl ./runtests.jl

By default, all tests are run.

---

Selective Test Execution

You can control which tests are run using command-line arguments.

Run a Quick Subset (Fast Tests Only)

julia --project=@/path/to/Norma.jl ./runtests.jl --quick

Use this when you want to verify functionality quickly without running the full suite.

Run Specific Tests by Index

julia --project=@/path/to/Norma.jl ./runtests.jl 1 3 5

List All Available Tests

julia --project=@/path/to/Norma.jl ./runtests.jl --list

---

Filtering by Name

To run tests whose filenames contain a given string (case-insensitive):

julia --project=@/path/to/Norma.jl ./runtests.jl --filter cube

You can combine filters with specific indices or --quick:

julia --project=@/path/to/Norma.jl ./runtests.jl --quick --filter dynamic
julia --project=@/path/to/Norma.jl ./runtests.jl 2 4 --filter static

---

Examples

To run the examples/contact/implicit-dynamic/2-bars example:

cd /path/to/Norma.jl/examples/contact/implicit-dynamic/2-bars
julia
]
activate .
using Norma
Norma.run("bars.yaml")

---

Profiling

To identify performance bottlenecks in Norma.jl, you can use Julia's built-in Profile module and visualize results with ProfileCanvas.jl:

Step 1: Enable Profiling

using Profile
include("/path/to/Norma.jl/src/Norma.jl")
cd("/path/to/Norma.jl/examples/contact/implicit-dynamic/2-bars")
@profile Norma.run("bars.yaml")

Step 2: Visualize with ProfileCanvas

using Pkg; Pkg.add("ProfileCanvas")
using ProfileCanvas
ProfileCanvas.canvas()

Command-Line Workflow

julia --project=@/path/to/Norma.jl -e 'using Profile; using Norma; cd("examples/contact/implicit-dynamic/2-bars"); @profile Norma.run("bars.yaml")' -E 'using ProfileCanvas; ProfileCanvas.canvas()'

---

Debugging

To enable debug-level logging in Norma.jl, use the JULIA_DEBUG environment variable:

JULIA_DEBUG=Norma julia --project=@/path/to/Norma.jl /path/to/Norma.jl/src/Norma.jl input.yaml

To add debug messages in code:

@debug "Starting simulation with input file: input.yaml"

To disable debug printing:

unset JULIA_DEBUG

Or suppress it at launch:

JULIA_DEBUG= julia --project=@/path/to/Norma.jl /path/to/Norma.jl/src/Norma.jl input.yaml

---

Troubleshooting

SSL Certificate Issues

cd ~/.julia/registries
git clone https://github.com/JuliaRegistries/General.git
export JULIA_SSL_CA_ROOTS_PATH=/etc/ssl/certs/ca-bundle.crt

Then retry installation.

---

License

Norma.jl is licensed under the BSD 3-Clause License. See LICENSE.md for details.