Skip to content

Commit

Permalink
Config Python setup for warning
Browse files Browse the repository at this point in the history
  • Loading branch information
facusapienza21 committed Jan 15, 2024
1 parent f0c9a67 commit 9ae62ee
Show file tree
Hide file tree
Showing 3 changed files with 68 additions and 21 deletions.
54 changes: 45 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,53 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

SphereUDE.jl is a Julia package for non-parametric regression of data supported in the three-dimensional sphere.
It implements a simple universal differential equation (UDE) that naturaly constrains path to lie in the sphere.
This has important application in Paleomagnetism, where the objective is to fit Aparent Polar Wander Paths (APWPs) to recunstruct continents past motion.
In addition to sphere regression, SphereUDE.jl implements a series of improvements over previous modelling methods, such as
- Explicit sphere constrint that allows for univesality of regression
It implements a simple universal differential equation (UDE) that naturally constrains path to lie in the sphere.
This has an important application in Paleomagnetism, where the objective is to fit Apparent Polar Wander Paths (APWPs) to reconstruct continents' past motion.
In addition to sphere regression, SphereUDE.jl implements a series of improvements over previous modeling methods, such as
- Explicit sphere constraint that allows for univesality of regression
- Regularization on the path to incorporate physical priors
- Incorporation of temporal and spatial uncertanties
- Uncertanty quantification capabilities
- Incorporation of temporal and spatial uncertainties
- Uncertainty quantification capabilities

## Usage

To train a model in new unobserved data, we need to define the _data_, _parameters_, and _regularization_ we want to use.
Data are defined as
```julia
data = SphereData(times=times_samples,
directions=X_true,
kappas=nothing,
L=L_true)

```
where `times` correspond to an array of the sampled times where we observed the three-dimensional vectors in `directions`.
We can further add an array `kappa` to specify uncertainty in the directions according to the Fisher distribution in the sphere.

It is possible to add different types of regularizations at the same time by specifying an array of the type `Regularization`, which specifies the type of regularization being used and the `diff_mode` that specifies the underlying automatic differentiation machinery being used to compute such gradients.
```julia
regs = [Regularization(order=1, power=1.0, λ=0.001, diff_mode="Finite Differences"),
Regularization(order=0, power=2.0, λ=0.1, diff_mode="Finite Differences")]

```
Finally, the parameters include the regularization together with other customizable training parameters:
```julia
params = SphereParameters(tmin=0.0, tmax=100.0,
reg=regs,
u0=[0.0, 0.0, -1.0], ωmax=1.0, reltol=1e-12, abstol=1e-12,
niter_ADAM=1000, niter_LBFGS=600)
```

Training is finally being done with
```julia
results = train(data, params, rng, nothing)
```
with `rng` a random seed used for the initial setup of the neural network.

Here there is a simple [example](https://github.com/facusapienza21/SphereUDE.jl/blob/main/examples/double_rotation/double_rotation.jl) for the reconstruction of two solid rotations using `SphereFit.jl`.

## Installing SphereUDE

In order to install `SphereUDE` in a given environment, just do in the REPL:
To install `SphereUDE` in a given environment, just do in the REPL:
```julia
julia> ] # enter Pkg mode
(@v1.9) pkg> activate MyEnvironment # or activate whatever path for the Julia environment
Expand All @@ -24,9 +60,9 @@ julia> ] # enter Pkg mode

## SphereUDE initialization: integration with Python

In order to make plots using Matplotlib, Cartopy, and PMagPy, we install both [PyCall.jl](https://github.com/JuliaPy/PyCall.jl) and [PyPlot.jl](https://github.com/JuliaPy/PyPlot.jl) and execute Python code directly from Julia. In order to do this setup manually, you can follow the next steps.
To make plots using Matplotlib, Cartopy, and PMagPy, we install both [PyCall.jl](https://github.com/JuliaPy/PyCall.jl) and [PyPlot.jl](https://github.com/JuliaPy/PyPlot.jl) and execute Python code directly from Julia. To do this setup manually, you can follow the next steps.

- Create a Python conda environmnet with all the requiremend packages using `conda env create -f environment.yml`.
- Create a Python conda environment with all the required packages using `conda env create -f environment.yml`.
- Inside the Julia REPL, install both `PyCall.jl` and `PyPlot.jl` with `] add PyCall, Pyplot`.
- Specify the Python path of the new environment with `ENV["PYTHON"] = ...`, where you should complete the path of the Python installation that shows when you do `conda activate SphereUDE`, `which python`.
- Inside the Julia REPL, execute `Pkg.build("PyCall")` to re-build PyCall with the new Python path.
Expand Down
18 changes: 6 additions & 12 deletions src/SphereUDE.jl
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,12 @@ include("train.jl")
include("plot.jl")

# Python libraries
const mpl_colors = PyNULL()
const mpl_colormap = PyNULL()
const sns = PyNULL()
const ccrs = PyNULL()
const feature = PyNULL()
const mpl_colors::PyObject = isdefined(SphereUDE, :mpl_colors) ? SphereUDE.mpl_colors : PyNULL()
const mpl_colormap::PyObject = isdefined(SphereUDE, :mpl_colormap) ? SphereUDE.mpl_colormap : PyNULL()
const sns::PyObject = isdefined(SphereUDE, :sns) ? SphereUDE.sns : PyNULL()
const ccrs::PyObject = isdefined(SphereUDE, :ccrs) ? SphereUDE.ccrs : PyNULL()
const feature::PyObject = isdefined(SphereUDE, :feature) ? SphereUDE.feature : PyNULL()

function __init__()
copy!(mpl_colors, pyimport("matplotlib.colors"))
copy!(mpl_colormap, pyimport("matplotlib.cm"))
copy!(sns, pyimport("seaborn"))
copy!(ccrs, pyimport("cartopy.crs"))
copy!(feature, pyimport("cartopy.feature"))
end
include("setup/config.jl")

end
17 changes: 17 additions & 0 deletions src/setup/config.jl
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
export mpl_colormap, mpl_colormap, sns, ccrs, feature

function __init__()

try
copy!(mpl_colors, pyimport("matplotlib.colors"))
copy!(mpl_colormap, pyimport("matplotlib.cm"))
copy!(sns, pyimport("seaborn"))
copy!(ccrs, pyimport("cartopy.crs"))
copy!(feature, pyimport("cartopy.feature"))
catch e
@warn "It looks like you have not installed and/or activated the virtual Python environment. \n
Please follow the guidelines in: https://github.com/facusapienza21/SphereUDE.jl#readme"
@warn exception=(e, catch_backtrace())
end

end

2 comments on commit 9ae62ee

@facusapienza21
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request updated: JuliaRegistries/General/98741

Tip: Release Notes

Did you know you can add release notes too? Just add markdown formatted text underneath the comment after the text
"Release notes:" and it will be added to the registry PR, and if TagBot is installed it will also be added to the
release that TagBot creates. i.e.

@JuliaRegistrator register

Release notes:

## Breaking changes

- blah

To add them here just re-invoke and the PR will be updated.

Tagging

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.1.0 -m "<description of version>" 9ae62eeeeb1df71094e705468868c2193bbbfb11
git push origin v0.1.0

Please sign in to comment.