Feature / julia implementation #237

mathgeek31415 · 2025-11-20T06:02:09Z

What type of PR is this? (check all applicable)

Description

This is a starting point for a Julia implementation of the MOLE library. Included are the 1D gradient, divergence, and laplacian operators, an implementation of the elliptic1D example from the MATLAB codebase, and unit tests.

Related Issues & Documents

Closes Start a Julia implementation of MOLE #228

QA Instructions, Screenshots, Recordings

Once the code is pulled, navigate to the mole/julia/MOLE.jl directory. Then, you can access any of the unit tests in the test/ folder, or you can run the example in the examples/ folder. Start a the project in a Julia REPL using julia --project=. which will bring in all the necessary packages utilized in the files.

Added/updated tests?

_We encourage you to test all code included with MOLE, including examples.

Yes
No, and this is why: please replace this line with details on why tests
have not been included
I need help with writing tests

Read Contributing Guide and Code of Conduct

I have read and followed the Contributing Guide and the Code of Conduct

[optional] Are there any post deployment tasks we need to perform?

Just remember to start the MOLE project in the Julia REPL with `julia --project=.``

[optional] What gif best describes this PR or how it makes you feel?

mathgeek31415 · 2025-11-20T06:05:22Z

Putting a draft PR here. The files I committed still need proper documentation. However, I believe all of the necessary functionality is present to be able to test the files.

Another modification (which I hope to include before merging this PR) is turning the operator files into modules, for better organization and importing within the Julia files.

mathgeek31415 · 2025-11-24T23:40:41Z

@valeriabarra I'm setting this PR ready for review, however I know you also requested that documentation be made with a tool like Documenter.jl. I'm still in the process of setting up Documenter for this new Julia implementation, but I have at least included docstrings for the operator files and example file.
Hopefully this is enough to at least merge this starter implementation (assuming no other issues are present), but if you would like the Documenter to be set up too then I can try to get that prepared before merging this PR.

To all reviewers, please let me know if you have any questions. Thank you.

jbrzensk

Hi @mathgeek31415 , thanks for tackling this. There is a lot of good things here. I added some comments in the code about some small specifics.

On a larger scale, I am thinking this needs to be broken into "src" and "examples" like the other languages. Maybe? we are having a meeting today and I will review with them.

Also, based on how long it took me to run the code, we definently need some documentation, mostly for how to get started. Whether that is adding to the README.md, or just putting a link to another README.md you have in the Julia directory, we need some explanation of how to load and run the code, and what needs to be installed.

I ran into a handfull of errors, don't know if that is because of my julia version (1.11.2), but we also need to decide on a base version to support.

But, thank you very much for contributing. A lot of this is on us to make the big decisions, but for now, this looks terrific. I'll update when we know more.

jbrzensk · 2025-12-01T21:02:49Z

julia/MOLE.jl/src/MOLE.jl

@@ -0,0 +1,10 @@
+module MOLE
+
+include("Divergence.jl")


should be lower case, throws an error in Linux:

LoadError: SystemError: opening file "/home/mole/julia/MOLE.jl/src/Divergence.jl": No such file or directory

@jbrzensk Sorry, I actually intended for the filenames to have a capital first letter. However, I started the files with a lowercase name, and didn't properly update the files through git (e.g. using git mv). I have hopefully corrected this in the update I will push later.

Hi @mathgeek31415, thank you for this tremendous contribution! Sorry for my delayed comment, but I actually prefer that the file names start with a lowercase letter (it's more customary this way)

Hi @valeriabarra, got it, thanks for the feedback! I just pushed a new commit with this update accordingly.

jbrzensk · 2025-12-01T21:03:55Z

julia/MOLE.jl/examples/elliptic1D.jl

@@ -0,0 +1,35 @@
+"""


""" creates the error:
ERROR: LoadError: cannot document the following expression:

using Plots

Apparently, there needs to be a space between the docstring and using statement! This was definitely my fault, I obviously didn't double check the file after adding in the docstring. This should be fixed in the update I will push later.

jbrzensk · 2025-12-01T21:08:10Z

julia/MOLE.jl/examples/elliptic1D.jl

+# Plot result
+p = scatter(grid,U,label="Approximated")
+plot!(p,grid,exp.(grid), label="Analytical")
+display(p)


Not sure where to put this, but if you run this in one shot from the command line:

julia --project=. examples/elliptic1D.jl

the plot is not shown. Either give explicit instructions on how to run from the Julia prompt, or add a stop that forces the render.

Just an example, but could add this to the end of the script:

println("\nPress Enter to close the plot and exit.") readline()

Thanks for the feedback @jbrzensk , this goes into the overall idea of adding a README (which I should have done, sorry). I've added the lines you suggested.

jbrzensk · 2025-12-01T21:09:04Z

julia/MOLE.jl/Project.toml

@@ -0,0 +1,5 @@
+name = "MOLE"
+


Reminder: we need to actually generate the uuid, date, etc for this. @valeriabarra would know best.

Thanks @jbrzensk. Is this information you would want to have before considering a merge?

@valeriabarra, I know there is a UUID Julia library, should this be used to generate the UUID? Or is there a specific format/sequence that should be used?

Hi @mathgeek31415 , thank you again for your tremendous contribution. I would start by reading the Julia documentation for packaging and environments.

Now, you have already gone one step ahead. But essentially, at the very beginning of your work, you could have used the generate function in the pkg (]) environment, as:

julia> ] pkg> generate MyNewPackage

And it would have created and assigned the UUID. I think you can still do it, but be careful that it might overwrite your existing Project.toml file. So place a back-up copy in a secure location before attempting this, please. Thank you

Thank you @valeriabarra, I think I've managed to re-generate the package with a UUID now included.

jbrzensk · 2025-12-01T21:16:41Z

julia/MOLE.jl/test/testDivergence.jl

@@ -0,0 +1,14 @@
+using Test, LinearAlgebra


@cpaolini @jcorbino This is a good replica, but we need a real test. @mathgeek31415 don't worry about this comment :)

jbrzensk · 2025-12-01T21:27:13Z

@cpaolini we also need a workflow to test this.

…g a script

mathgeek31415 · 2025-12-08T08:11:05Z

@jbrzensk I've pushed an update, per our conversations above. Additionally, I've included (the beginnings of) a README file. I would appreciate any feedback on how I can make the README clearer. My apologies again for not originally including any instructions; this is definitely something crucial that should have been included.

Hopefully everything else has been addressed, but please let me know if you find any other errors. Thank you!

Edit: Also changed the filenames for the operators to be all lowercase, and updated the names in the MOLE.jl file.

valeriabarra · 2025-12-08T18:17:57Z

julia/MOLE.jl/README.md

+## Using MOLE.jl at the command line
+
+To run a Julia script at the command line using MOLE.jl, To use MOLE.jl in a Julia REPL, navigate to the location where MOLE has been cloned to, then navigate to ```mole/julia/MOLE.jl```. Once here use the following command (here, we will run "elliptic1D" from the examples directory):
+> ```julia --project=. examples/elliptic1D.jl```


Before being able to run an example, we need to tell users to instantiate/precoimpile the package. Here are the instructions from the CLI. You can translate to similar instructions from within the REPL for the section above (that means, first tell them to switch to pkg (]) mode and then type instantiate and precompile).

julia --project=. -e 'using Pkg; Pkg.instantiate()' julia --project=. -e 'using Pkg; Pkg.precompile()' julia --project=. examples/elliptic1D.jl

valeriabarra · 2025-12-08T18:24:12Z

julia/MOLE.jl/test/testDivergence.jl

@@ -0,0 +1,14 @@
+using Test, LinearAlgebra


I can't comment at the folder level (only on a specific line of code in a file), but inside the test/ folder, we want to have a runtests.jl file that collects all the different tests. It is very common to group tests with the @testset macro followed by a descriptive string for that group of tests and the begin and end keywords to enclose the group of tests.

If we are envisioning to have multiple separate unit testing files, we can have a table-of-content style list in the runtests.jl file (see ClimaCore's runtests.jl for instance)

Thank you for the feedback @valeriabarra , I re-structured the test directory to include a runtests file that aggregates the separate test files for the operators. From the MOLE.jl directory, a user should now be able to start the REPL (using, e.g. julia --project=.), enter the "pkg" mode, and run test to start the different unit tests.
I will put this into the documentation, but just wanted to copy the instructions here too.

valeriabarra · 2025-12-08T18:37:51Z

@valeriabarra I'm setting this PR ready for review, however I know you also requested that documentation be made with a tool like Documenter.jl. I'm still in the process of setting up Documenter for this new Julia implementation, but I have at least included docstrings for the operator files and example file. Hopefully this is enough to at least merge this starter implementation (assuming no other issues are present), but if you would like the Documenter to be set up too then I can try to get that prepared before merging this PR.

To all reviewers, please let me know if you have any questions. Thank you.

Hi @mathgeek31415 thank you again for this amazing contribution!

Yes, it would be nice to have (at least a first initial draft) of the documentation via Documenter.jl.

I think we will end up having two separate HTML-based documentation web pages, one for the base MATLAB and C++ implementation (which uses Sphinx and is hosted on ReadTheDocs), and one for the Julia implementation. The latter will be linked from the ReadTheDocs one. Similar to what was done for the LibCEED.jl documentation that is linked from their ReadTheDocs one.

Unless we can invest some time in learning if the DocumenterInterLinks option for embedding Julia documentation in a sphinx project is a viable and worthwhile option.

valeriabarra · 2025-12-12T22:44:20Z

@valeriabarra I'm setting this PR ready for review, however I know you also requested that documentation be made with a tool like Documenter.jl. I'm still in the process of setting up Documenter for this new Julia
Unless we can invest some time in learning if the DocumenterInterLinks option for embedding Julia documentation in a sphinx project is a viable and worthwhile option.

Just to circle back on my previous comment, for now, it is better to keep things simple. We want to pursue the simple Julia documentation via Documenter.jl even if this means having two separate HTML-based doc pages. We will link the Julia one from the main ReadTheDocs one. Thank you

mathgeek31415 · 2025-12-14T23:35:49Z

@valeriabarra I'm setting this PR ready for review, however I know you also requested that documentation be made with a tool like Documenter.jl. I'm still in the process of setting up Documenter for this new Julia
Unless we can invest some time in learning if the DocumenterInterLinks option for embedding Julia documentation in a sphinx project is a viable and worthwhile option.

Just to circle back on my previous comment, for now, it is better to keep things simple. We want to pursue the simple Julia documentation via Documenter.jl even if this means having two separate HTML-based doc pages. We will link the Julia one from the main ReadTheDocs one. Thank you

Thank you for the update @valeriabarra , I will work on getting a first draft of the documentation via Documenter.jl up and running. I hope to push an update sometime this week.

mathgeek31415 · 2025-12-24T00:34:53Z

Hi @jbrzensk @valeriabarra ,
Just wanted to provide some updates. I've made some recent commits, addressing the following:

MOLE.jl Project.toml file now has a UUID.
Revised the test directory to have a runtests.jl driver. To run the current collection of unit tests, first start the Julia REPL via julia --project=. (from the julia/MOLE.jl directory), enter the pkg ] mode, then run the command test.
Added the beginnings of a documentation site - this is a very minimum viable version, and I would appreciate feedback on how to make it clearer.
- I also removed the README.md since the documentation site now has this information.

In addition to any errors encountered while testing, it would be great to have feedback on the following:

Are there any critical instructions missing from the "Getting Started", "Installation", or "Using" sections of the documentation?
Should the all of the source files include the copyright and licensing text that the C++ and MATLAB files have? (I assume that the eventual answer is "yes", but I wasn't sure if I should add this text yet.)

Thank you very much for your help!

mathgeek31415 added 4 commits November 19, 2025 01:36

initial commit; implemented the div and grad operators

b074226

completed laplacian operator and robinBC function

50be4c0

completed 1D elliptic PDE example, and unit tests for div and grad

d77c135

edited elliptic1D example and added test for laplacian operator

cfc1773

mathgeek31415 added 3 commits November 24, 2025 01:42

created central MOLE file; small edits to test files

b357b7e

Updated src files to have 'using MOLE' package

f25ab7f

small edits

2003238

mathgeek31415 marked this pull request as ready for review November 24, 2025 23:36

jbrzensk reviewed Dec 1, 2025

View reviewed changes

mathgeek31415 added 3 commits December 7, 2025 21:40

Changed case of first letter of src filenames

275ec69

Added code to prevent plot window from closing at command line

9a483b0

added README file with instructions for activating MOLE.jl and runnin…

37ea76a

…g a script

changed src filenames to be lowercase and updated MOLE.jl file

d89a7b1

valeriabarra reviewed Dec 8, 2025

View reviewed changes

mathgeek31415 added 5 commits December 18, 2025 21:04

re-generated the Project.toml file with a UUID

ad449c7

added dependencies for MOLE.jl

b8b4015

updated test directory with Project file and runtests.jl driver

0ea21f6

initial version of documentation site for MOLE.jl

4a466f5

removed README.md file in place of documentation page

c6dc044

Feature / julia implementation #237

Are you sure you want to change the base?

Feature / julia implementation #237

Uh oh!

Conversation

mathgeek31415 commented Nov 20, 2025

What type of PR is this? (check all applicable)

Description

Related Issues & Documents

QA Instructions, Screenshots, Recordings

Added/updated tests?

Read Contributing Guide and Code of Conduct

[optional] Are there any post deployment tasks we need to perform?

[optional] What gif best describes this PR or how it makes you feel?

Uh oh!

mathgeek31415 commented Nov 20, 2025

Uh oh!

mathgeek31415 commented Nov 24, 2025

Uh oh!

jbrzensk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbrzensk commented Dec 1, 2025

Uh oh!

mathgeek31415 commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

valeriabarra commented Dec 8, 2025

Uh oh!

valeriabarra commented Dec 12, 2025

Uh oh!

mathgeek31415 commented Dec 14, 2025

Uh oh!

mathgeek31415 commented Dec 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mathgeek31415 commented Dec 8, 2025 •

edited

Loading