Norma

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

---

Table of Contents

1. Features
2. Installation
3. Running the Code
4. Testing
5. Examples
6. Profiling
7. Debugging
8. Troubleshooting

---

Features

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

---

Installation

Clone the Repository

cd /some_path
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=@. /some_path/Norma.jl/src/Norma.jl input.yaml

To run Norma interactively from a Julia session:

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

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

cd("examples/ahead/overlap/cuboid/dynamic")
Norma.run("cuboid.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.

---

Testing

To run the test suite using the Julia REPL, following standard Julia conventions:

using Pkg
Pkg.test()

Alternatively, from the command line:

julia --project=@. ./runtests.jl

---

Examples

To run the examples/ahead/overlap/cuboid/dynamic example:

cd /some_path/Norma.jl/examples/ahead/overlap/cuboid/dynamic
julia
]
activate .
using Norma
Norma.run("cuboid.yaml")

---

Profiling

To identify performance bottlenecks in Norma.jl, you can use Julia's built-in Profile module and visualization tools. The following steps demonstrate how to profile the Norma.run("input.yaml") function:

Step 1: Enable Profiling

Run the simulation with the @profile macro:

using Profile

include("/some_path/Norma.jl/src/Norma.jl")
cd("/some_path/Norma.jl/examples/ahead/overlap/cuboid/dynamic")
@profile Norma.run("cuboid.yaml")

Step 2: View the Profiling Results

Print a summary of the profiling data:

Profile.print()

This will display the most frequently hit lines of code during execution.

Step 3: Visualize with ProfileView

To generate a graphical flame graph of the profiling results, install and use ProfileView:

using Pkg
Pkg.add("ProfileView")
using ProfileView

ProfileView.view()  # Open the visualization

This will display a flame graph where the horizontal axis represents function calls and their cumulative time, allowing you to pinpoint performance bottlenecks.

Step 4: Optional: Export Results as HTML

For more interactive analysis, use StatProfilerHTML:

1. Install the package:

   Pkg.add("StatProfilerHTML")

2. Generate and open an HTML report:

   using StatProfilerHTML
   StatProfilerHTML.open()

Example Command-Line Workflow

From the command line, you can combine profiling with Julia's REPL:

julia --project=@. -e 'using Profile; using Norma; cd("examples/ahead/overlap/cuboid/dynamic"); @profile Norma.run("cuboid.yaml")' -E 'using ProfileView; ProfileView.view()'

This will profile the code and open the flame graph for analysis.

---

Debugging

To enable debug-level logging and printing statements in Norma.jl, you can use the JULIA_DEBUG environment variable. This allows fine-grained control over debug messages using Julia's built-in logging framework.

Step 1: Enable Debug Printing

To enable debug messages for the Norma module, prepend JULIA_DEBUG=Norma to the Julia command:

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

This will display all debug-level messages from the Norma module.

Step 2: Adding Debug Statements

To add debug-level messages in the code, use the @debug macro:

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

The @debug macro allows you to print messages only when debug-level logging is enabled, keeping the output clean in production runs.

Step 3: Verifying Debug Outputs

After enabling debug printing, you will see detailed debug messages like this:

┌ Debug: Starting simulation with input file: input.yaml
└ @ Norma src/Norma.jl:42

These messages include the file, module, and line number where the debug statement was triggered.

Step 4: Disabling Debug Printing

To disable debug messages, simply remove or unset the JULIA_DEBUG variable:

unset JULIA_DEBUG

Alternatively, set it to a higher logging level (e.g., INFO):

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

---

Troubleshooting

SSL Certificate Issues

If you encounter SSL certificate errors during setup, follow these steps:

1. Go to ~/.julia/registries and manually clone the Julia General Registry:

   cd ~/.julia/registries
   git clone https://github.com/JuliaRegistries/General.git

2. Set the SSL certificate path:

   export JULIA_SSL_CA_ROOTS_PATH=/etc/ssl/certs/ca-bundle.crt

3. Retry the installation workflow.