diff --git a/dev/developers/contributing/index.html b/dev/developers/contributing/index.html index 9ceec94..4893da3 100644 --- a/dev/developers/contributing/index.html +++ b/dev/developers/contributing/index.html @@ -9,12 +9,12 @@ Deleted no artifacts, repos, packages or scratchspaces
julia> Pkg.develop("EquationOfStateRecipes") Cloning git-repo `https://github.com/MineralsCloud/EquationOfStateRecipes.jl.git` Resolving package versions... Updating `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl/docs/Project.toml` - [8d49d7c9] ~ EquationOfStateRecipes v0.4.1 `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl` ⇒ v0.4.1 `~/.julia/dev/EquationOfStateRecipes` + [8d49d7c9] ~ EquationOfStateRecipes v0.5.0 `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl` ⇒ v0.5.0 `~/.julia/dev/EquationOfStateRecipes` Updating `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl/docs/Manifest.toml` - [8d49d7c9] ~ EquationOfStateRecipes v0.4.1 `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl` ⇒ v0.4.1 `~/.julia/dev/EquationOfStateRecipes`

Then the package will be cloned to your local machine. On *nix systems, the default path is ~/.julia/dev/EquationOfStateRecipes unless you modify the JULIA_DEPOT_PATH environment variable. If you're on Windows, this will be C:\\Users\\<my_name>\\.julia\\dev\\EquationOfStateRecipes. In the following text, we will call it PKGROOT.

Go to PKGROOT, start a new Julia session, and run

julia> using Pkg
julia> Pkg.instantiate()Precompiling project...
+  [8d49d7c9] ~ EquationOfStateRecipes v0.5.0 `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl` ⇒ v0.5.0 `~/.julia/dev/EquationOfStateRecipes`

Then the package will be cloned to your local machine. On *nix systems, the default path is ~/.julia/dev/EquationOfStateRecipes unless you modify the JULIA_DEPOT_PATH environment variable. If you're on Windows, this will be C:\\Users\\<my_name>\\.julia\\dev\\EquationOfStateRecipes. In the following text, we will call it PKGROOT.

Go to PKGROOT, start a new Julia session, and run

julia> using Pkg
julia> Pkg.instantiate()Precompiling project...
   ✓ EquationOfStateRecipes
   ✓ EquationOfStateRecipes → PlotsExt
-  2 dependencies successfully precompiled in 9 seconds. 180 already precompiled.
+  2 dependencies successfully precompiled in 8 seconds. 180 already precompiled.
   2 dependencies precompiled but different versions are currently loaded. Restart julia to access the new versions

to instantiate the project.

Step 4: checkout a new branch

Note

In the following, replace any instance of GITHUB_ACCOUNT with your GitHub username.

The next step is to check out a development branch. In a terminal (or command prompt on Windows), run:

$ cd ~/.julia/dev/EquationOfStateRecipes
 
 $ git remote add GITHUB_ACCOUNT https://github.com/GITHUB_ACCOUNT/EquationOfStateRecipes.jl.git
@@ -47,4 +47,4 @@
 
 $ git checkout main
 
-$ git pull
Note

If you have suggestions to improve this guide, please make a pull request! It's particularly helpful if you do this after your first pull request because you'll know all the parts that could be explained better.

Thanks for contributing to EquationOfStateRecipes!

+$ git pull
Note

If you have suggestions to improve this guide, please make a pull request! It's particularly helpful if you do this after your first pull request because you'll know all the parts that could be explained better.

Thanks for contributing to EquationOfStateRecipes!

diff --git a/dev/developers/design-principles/index.html b/dev/developers/design-principles/index.html index f321f33..a7c9d9c 100644 --- a/dev/developers/design-principles/index.html +++ b/dev/developers/design-principles/index.html @@ -13,4 +13,4 @@ end return y end

and thus using such a macro as the interface is not preferred when possible. However, a macro like @muladd is trivial to picture on a code (it recursively transforms a*b + c to muladd(a,b,c) for more accuracy and efficiency), so using such a macro for example:

julia> @macroexpand(@muladd k3 = f(t + c3 * dt, @. uprev + dt * (a031 * k1 + a032 * k2)))
-:(k3 = f((muladd)(c3, dt, t), (muladd).(dt, (muladd).(a032, k2, (*).(a031, k1)), uprev)))

is recommended. Some macros in this category are:

Some performance macros, like @simd, @threads, or @turbo from LoopVectorization.jl, make an exception in that their generated code may be foreign to many users. However, they still are classified as appropriate uses as they are syntactic sugar since they do (or should) not change the behavior of the program in measurable ways other than performance.

Errors should be caught as early as possible, and error messages should be made contextually clear for newcomers

Whenever possible, defensive programming should be used to check for potential errors before they are encountered deeper within a package. For example, if one knows that f(u0,p) will error unless u0 is the size of p, this should be caught at the start of the function to throw a domain specific error, for example "parameters and initial condition should be the same size".

Subpackaging and interface packages is preferred over conditional modules via Requires.jl

Requires.jl should be avoided at all costs. If an interface package exists, such as ChainRulesCore.jl for defining automatic differentiation rules without requiring a dependency on the whole ChainRules.jl system, or RecipesBase.jl which allows for defining Plots.jl plot recipes without a dependency on Plots.jl, a direct dependency on these interface packages is preferred.

Otherwise, instead of resorting to a conditional dependency using Requires.jl, it is preferred one creates subpackages, i.e. smaller independent packages kept within the same GitHub repository with independent versioning and package management. An example of this is seen in Optimization.jl which has subpackages like OptimizationBBO.jl for BlackBoxOptim.jl support.

Some important interface packages to be aware of include:

Functions should either attempt to be non-allocating and reuse caches, or treat inputs as immutable

Mutating codes and non-mutating codes fall into different worlds. When a code is fully immutable, the compiler can better reason about dependencies, optimize the code, and check for correctness. However, many times a code making the fullest use of mutation can outperform even what the best compilers of today can generate. That said, the worst of all worlds is when code mixes mutation with non-mutating code. Not only is this a mishmash of coding styles, it has the potential non-locality and compiler proof issues of mutating code while not fully benefiting from the mutation.

Out-of-place and immutability is preferred when sufficient performant

Mutation is used to get more performance by decreasing the amount of heap allocations. However, if it's not helpful for heap allocations in a given spot, do not use mutation. Mutation is scary and should be avoided unless it gives an immediate benefit. For example, if matrices are sufficiently large, then A*B is as fast as mul!(C,A,B), and thus writing A*B is preferred (unless the rest of the function is being careful about being fully non-allocating, in which case this should be mul! for consistency).

Similarly, when defining types, using struct is preferred to mutable struct unless mutating the struct is a common occurrence. Even if mutating the struct is a common occurrence, see whether using Setfield.jl is sufficient. The compiler will optimize the construction of immutable structs, and thus this can be more efficient if it's not too much of a code hassle.

Tests should attempt to cover a wide gamut of input types

Code coverage numbers are meaningless if one does not consider the input types. For example, one can hit all the code with Array, but that does not test whether CuArray is compatible! Thus, it's always good to think of coverage not in terms of lines of code but in terms of type coverage. A good list of number types to think about are:

Array types to think about testing are:

When in doubt, a submodule should become a subpackage or separate package

Each package should focus on one core idea. If there's something separate enough to be a submodule, could it instead be a separate well-tested and documented package to be used by other packages? Most likely yes.

Globals should be avoided whenever possible

Global variables should be avoided whenever possible. When required, global variables should be constants and have an all uppercase name separated with underscores (e.g. MY_CONSTANT). They should be defined at the top of the file, immediately after imports and exports but before an __init__ function. If you truly want mutable global style behavior you may want to look into mutable containers.

Type-stable and type-grounded code is preferred wherever possible

Type-stable and type-grounded code helps the compiler create not only more optimized code, but also faster to compile code. Always keep containers well-typed, functions specializing on the appropriate arguments, and types concrete.

Closures should be avoided whenever possible

Closures can cause accidental type instabilities that are difficult to track down and debug; in the long run it saves time to always program defensively and avoid writing closures in the first place, even when a particular closure would not have been problematic. A similar argument applies to reading code with closures; if someone is looking for type instabilities, this is faster to do when code does not contain closures. See examples here.

Furthermore, if you want to update variables in an outer scope, do so explicitly with Refs or self defined structs.

Numerical functionality should use the appropriate generic numerical interfaces

While you can use A\b to do a linear solve inside a package, that does not mean that you should. This interface is only sufficient for performing factorizations, and so that limits the scaling choices, the types of A that can be supported, etc. Instead, linear solves within packages should use LinearSolve.jl. Similarly, nonlinear solves should use NonlinearSolve.jl. Optimization should use Optimization.jl. Etc. This allows the full generic choice to be given to the user without depending on every solver package (effectively recreating the generic interfaces within each package).

Functions should capture one underlying principle

Functions mean one thing. Every dispatch of + should be "the meaning of addition on these types". While in theory you could add dispatches to + that mean something different, that will fail in generic code for which + means addition. Thus, for generic code to work, code needs to adhere to one meaning for each function. Every dispatch should be an instantiation of that meaning.

Internal choices should be exposed as options whenever possible

Whenever possible, numerical values and choices within scripts should be exposed as options to the user. This promotes code reusability beyond the few cases the author may have expected.

Prefer code reuse over rewrites whenever possible

If a package has a function you need, use the package. Add a dependency if you need to. If the function is missing a feature, prefer to add that feature to said package and then add it as a dependency. If the dependency is potentially troublesome, for example because it has a high load time, prefer to spend time helping said package fix these issues and add the dependency. Only when it does not seem possible to make the package "good enough" should using the package be abandoned. If it is abandoned, consider building a new package for this functionality as you need it, and then make it a dependency.

Prefer to not shadow functions

In Julia, two functions can share the same name if they belong to different namespaces. For example, X.f and Y.f can be two different functions, with different dispatches, but the same name. This should be avoided whenever possible. Instead of creating MyPackage.sort, consider adding dispatches to Base.sort for your types if these new dispatches match the underlying principle of the function. If they don't, it would be preferable to use a different name. While using MyPackage.sort is not conflicting, it is going to be confusing for most people unfamiliar with your code, so MyPackage.special_sort would be more helpful to newcomers reading the code.

+:(k3 = f((muladd)(c3, dt, t), (muladd).(dt, (muladd).(a032, k2, (*).(a031, k1)), uprev)))

is recommended. Some macros in this category are:

Some performance macros, like @simd, @threads, or @turbo from LoopVectorization.jl, make an exception in that their generated code may be foreign to many users. However, they still are classified as appropriate uses as they are syntactic sugar since they do (or should) not change the behavior of the program in measurable ways other than performance.

Errors should be caught as early as possible, and error messages should be made contextually clear for newcomers

Whenever possible, defensive programming should be used to check for potential errors before they are encountered deeper within a package. For example, if one knows that f(u0,p) will error unless u0 is the size of p, this should be caught at the start of the function to throw a domain specific error, for example "parameters and initial condition should be the same size".

Subpackaging and interface packages is preferred over conditional modules via Requires.jl

Requires.jl should be avoided at all costs. If an interface package exists, such as ChainRulesCore.jl for defining automatic differentiation rules without requiring a dependency on the whole ChainRules.jl system, or RecipesBase.jl which allows for defining Plots.jl plot recipes without a dependency on Plots.jl, a direct dependency on these interface packages is preferred.

Otherwise, instead of resorting to a conditional dependency using Requires.jl, it is preferred one creates subpackages, i.e. smaller independent packages kept within the same GitHub repository with independent versioning and package management. An example of this is seen in Optimization.jl which has subpackages like OptimizationBBO.jl for BlackBoxOptim.jl support.

Some important interface packages to be aware of include:

Functions should either attempt to be non-allocating and reuse caches, or treat inputs as immutable

Mutating codes and non-mutating codes fall into different worlds. When a code is fully immutable, the compiler can better reason about dependencies, optimize the code, and check for correctness. However, many times a code making the fullest use of mutation can outperform even what the best compilers of today can generate. That said, the worst of all worlds is when code mixes mutation with non-mutating code. Not only is this a mishmash of coding styles, it has the potential non-locality and compiler proof issues of mutating code while not fully benefiting from the mutation.

Out-of-place and immutability is preferred when sufficient performant

Mutation is used to get more performance by decreasing the amount of heap allocations. However, if it's not helpful for heap allocations in a given spot, do not use mutation. Mutation is scary and should be avoided unless it gives an immediate benefit. For example, if matrices are sufficiently large, then A*B is as fast as mul!(C,A,B), and thus writing A*B is preferred (unless the rest of the function is being careful about being fully non-allocating, in which case this should be mul! for consistency).

Similarly, when defining types, using struct is preferred to mutable struct unless mutating the struct is a common occurrence. Even if mutating the struct is a common occurrence, see whether using Setfield.jl is sufficient. The compiler will optimize the construction of immutable structs, and thus this can be more efficient if it's not too much of a code hassle.

Tests should attempt to cover a wide gamut of input types

Code coverage numbers are meaningless if one does not consider the input types. For example, one can hit all the code with Array, but that does not test whether CuArray is compatible! Thus, it's always good to think of coverage not in terms of lines of code but in terms of type coverage. A good list of number types to think about are:

Array types to think about testing are:

When in doubt, a submodule should become a subpackage or separate package

Each package should focus on one core idea. If there's something separate enough to be a submodule, could it instead be a separate well-tested and documented package to be used by other packages? Most likely yes.

Globals should be avoided whenever possible

Global variables should be avoided whenever possible. When required, global variables should be constants and have an all uppercase name separated with underscores (e.g. MY_CONSTANT). They should be defined at the top of the file, immediately after imports and exports but before an __init__ function. If you truly want mutable global style behavior you may want to look into mutable containers.

Type-stable and type-grounded code is preferred wherever possible

Type-stable and type-grounded code helps the compiler create not only more optimized code, but also faster to compile code. Always keep containers well-typed, functions specializing on the appropriate arguments, and types concrete.

Closures should be avoided whenever possible

Closures can cause accidental type instabilities that are difficult to track down and debug; in the long run it saves time to always program defensively and avoid writing closures in the first place, even when a particular closure would not have been problematic. A similar argument applies to reading code with closures; if someone is looking for type instabilities, this is faster to do when code does not contain closures. See examples here.

Furthermore, if you want to update variables in an outer scope, do so explicitly with Refs or self defined structs.

Numerical functionality should use the appropriate generic numerical interfaces

While you can use A\b to do a linear solve inside a package, that does not mean that you should. This interface is only sufficient for performing factorizations, and so that limits the scaling choices, the types of A that can be supported, etc. Instead, linear solves within packages should use LinearSolve.jl. Similarly, nonlinear solves should use NonlinearSolve.jl. Optimization should use Optimization.jl. Etc. This allows the full generic choice to be given to the user without depending on every solver package (effectively recreating the generic interfaces within each package).

Functions should capture one underlying principle

Functions mean one thing. Every dispatch of + should be "the meaning of addition on these types". While in theory you could add dispatches to + that mean something different, that will fail in generic code for which + means addition. Thus, for generic code to work, code needs to adhere to one meaning for each function. Every dispatch should be an instantiation of that meaning.

Internal choices should be exposed as options whenever possible

Whenever possible, numerical values and choices within scripts should be exposed as options to the user. This promotes code reusability beyond the few cases the author may have expected.

Prefer code reuse over rewrites whenever possible

If a package has a function you need, use the package. Add a dependency if you need to. If the function is missing a feature, prefer to add that feature to said package and then add it as a dependency. If the dependency is potentially troublesome, for example because it has a high load time, prefer to spend time helping said package fix these issues and add the dependency. Only when it does not seem possible to make the package "good enough" should using the package be abandoned. If it is abandoned, consider building a new package for this functionality as you need it, and then make it a dependency.

Prefer to not shadow functions

In Julia, two functions can share the same name if they belong to different namespaces. For example, X.f and Y.f can be two different functions, with different dispatches, but the same name. This should be avoided whenever possible. Instead of creating MyPackage.sort, consider adding dispatches to Base.sort for your types if these new dispatches match the underlying principle of the function. If they don't, it would be preferable to use a different name. While using MyPackage.sort is not conflicting, it is going to be confusing for most people unfamiliar with your code, so MyPackage.special_sort would be more helpful to newcomers reading the code.

diff --git a/dev/developers/style-guide/index.html b/dev/developers/style-guide/index.html index 3878db9..39bb096 100644 --- a/dev/developers/style-guide/index.html +++ b/dev/developers/style-guide/index.html @@ -5,4 +5,4 @@ julia> using JuliaFormatter: format -julia> format("docs"); format("src"); format("test")
Info

A continuous integration check verifies that all PRs made to EquationOfStateRecipes have passed the formatter.

The following sections outline extra style guide points that are not fixed automatically by JuliaFormatter.

Use the Julia extension for Visual Studio Code

Please use Visual Studio Code with the Julia extension to edit, format, and test your code. For the time being, we do not recommend using editors other than Visual Studio Code to edit your code.

This extension already has JuliaFormatter integrated. So to format your code, follow the steps listed here.

+julia> format("docs"); format("src"); format("test")
Info

A continuous integration check verifies that all PRs made to EquationOfStateRecipes have passed the formatter.

The following sections outline extra style guide points that are not fixed automatically by JuliaFormatter.

Use the Julia extension for Visual Studio Code

Please use Visual Studio Code with the Julia extension to edit, format, and test your code. For the time being, we do not recommend using editors other than Visual Studio Code to edit your code.

This extension already has JuliaFormatter integrated. So to format your code, follow the steps listed here.

diff --git a/dev/index.html b/dev/index.html index 8c36755..3c4ca61 100644 --- a/dev/index.html +++ b/dev/index.html @@ -2,11 +2,11 @@ EquationOfStateRecipes · EquationOfStateRecipes.jl
Edit on GitHub

EquationOfStateRecipes

Documentation for EquationOfStateRecipes.

See the Index for the complete list of documented functions and types.

The code, which is hosted on GitHub, is tested using various continuous integration services for its validity.

This repository is created and maintained by @singularitti, and contributions are highly welcome.

Package features

This package contains recipes for EquationsOfStateOfSolids.jl which work with Plots.jl.

Installation

The package can be installed with the Julia package manager. From the Julia REPL, type ] to enter the Pkg mode and run:

pkg> add EquationOfStateRecipes

Or, equivalently, via Pkg.jl:

julia> import Pkg; Pkg.add("EquationOfStateRecipes")   Resolving package versions...
    Installed EquationOfStateRecipes ─ v0.4.1
     Updating `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl/docs/Project.toml`
-  [8d49d7c9] ~ EquationOfStateRecipes v0.4.1 `~/.julia/dev/EquationOfStateRecipes` ⇒ v0.4.1
+  [8d49d7c9] ~ EquationOfStateRecipes v0.5.0 `~/.julia/dev/EquationOfStateRecipes` ⇒ v0.4.1
     Updating `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl/docs/Manifest.toml`
-  [8d49d7c9] ~ EquationOfStateRecipes v0.4.1 `~/.julia/dev/EquationOfStateRecipes` ⇒ v0.4.1
+  [8d49d7c9] ~ EquationOfStateRecipes v0.5.0 `~/.julia/dev/EquationOfStateRecipes` ⇒ v0.4.1
 Precompiling project...
   ✓ EquationOfStateRecipes
   ✓ EquationOfStateRecipes → PlotsExt
-  2 dependencies successfully precompiled in 9 seconds. 180 already precompiled.
-  2 dependencies precompiled but different versions are currently loaded. Restart julia to access the new versions

Documentation

  • STABLE — documentation of the most recently tagged version.
  • DEV — documentation of the in-development version.

Project status

The package is developed for and tested against Julia v1.6 and above on Linux, macOS, and Windows.

Questions and contributions

You can post usage questions on our discussion page.

We welcome contributions, feature requests, and suggestions. If you encounter any problems, please open an issue. The Contributing page has a few guidelines that should be followed when opening pull requests and contributing code.

Manual outline

Library outline

Index

+ 2 dependencies successfully precompiled in 8 seconds. 180 already precompiled. + 2 dependencies precompiled but different versions are currently loaded. Restart julia to access the new versions

Documentation

Project status

The package is developed for and tested against Julia v1.6 and above on Linux, macOS, and Windows.

Questions and contributions

You can post usage questions on our discussion page.

We welcome contributions, feature requests, and suggestions. If you encounter any problems, please open an issue. The Contributing page has a few guidelines that should be followed when opening pull requests and contributing code.

Manual outline

Library outline

Index

diff --git a/dev/lib/public/index.html b/dev/lib/public/index.html index beca5a5..5492bf4 100644 --- a/dev/lib/public/index.html +++ b/dev/lib/public/index.html @@ -7,12 +7,12 @@ plot!(eos::BulkModulusEquation, volumes, args...; kw...) plot!(plotobj, eos::EnergyEquation, volumes, args...; kw...) plot!(plotobj, eos::PressureEquation, volumes, args...; kw...) -plot!(plotobj, eos::BulkModulusEquation, volumes, args...; kw...)

Plot the energy/pressure/bulk modulus versus volumes curve given an equation of state.

source
EquationOfStateRecipes.energyplot — Function
energyplot(params::Parameters, volumes, args...; kw...)
+plot!(plotobj, eos::BulkModulusEquation, volumes, args...; kw...)

Plot the energy/pressure/bulk modulus versus volumes curve given an equation of state.

source
EquationOfStateRecipes.energyplot — Function
energyplot(params::Parameters, volumes, args...; kw...)
 energyplot!(params::Parameters, volumes, args...; kw...)
-energyplot!(plotobj, params::Parameters, volumes, args...; kw...)

Plot the energy versus volumes curves given the parameters of equations of state.

source
EquationOfStateRecipes.pressureplot — Function
pressureplot(params::Parameters, volumes, args...; kw...)
+energyplot!(plotobj, params::Parameters, volumes, args...; kw...)

Plot the energy versus volumes curves given the parameters of equations of state.

source
EquationOfStateRecipes.pressureplot — Function
pressureplot(params::Parameters, volumes, args...; kw...)
 pressureplot!(params::Parameters, volumes, args...; kw...)
-pressureplot!(plotobj, params::Parameters, volumes, args...; kw...)

Plot the pressure versus volumes curves given the parameters of equations of state.

source
EquationOfStateRecipes.bulkmodulusplot — Function
bulkmodulusplot(params::Parameters, volumes, args...; kw...)
+pressureplot!(plotobj, params::Parameters, volumes, args...; kw...)

Plot the pressure versus volumes curves given the parameters of equations of state.

source
EquationOfStateRecipes.bulkmodulusplot — Function
bulkmodulusplot(params::Parameters, volumes, args...; kw...)
 bulkmodulusplot!(params::Parameters, volumes, args...; kw...)
-bulkmodulusplot!(plotobj, params::Parameters, volumes, args...; kw...)

Plot the bulk modulus versus volumes curves given the parameters of equations of state.

source
EquationOfStateRecipes.energypressureplot — Function
energypressureplot(params::Parameters, volumes, args...; layout=(1, 2), kw...)
+bulkmodulusplot!(plotobj, params::Parameters, volumes, args...; kw...)

Plot the bulk modulus versus volumes curves given the parameters of equations of state.

source
EquationOfStateRecipes.energypressureplot — Function
energypressureplot(params::Parameters, volumes, args...; layout=(1, 2), kw...)
 energypressureplot!(params::Parameters, volumes, args...; layout=(1, 2), kw...)
-energypressureplot!(plotobj, params::Parameters, volumes, args...; layout=(1, 2), kw...)

Create a graph that shows the energy/pressure versus volume curves using the given parameters of equations of state on the same horizontal axis.

Warning

To use this function, you must specify the layout keyword argument as either (1, 2) or (2, 1)!

source
+energypressureplot!(plotobj, params::Parameters, volumes, args...; layout=(1, 2), kw...)

Create a graph that shows the energy/pressure versus volume curves using the given parameters of equations of state on the same horizontal axis.

Warning

To use this function, you must specify the layout keyword argument as either (1, 2) or (2, 1)!

source diff --git a/dev/man/bv.svg b/dev/man/bv.svg index 2c4f47f..c738c31 100644 --- a/dev/man/bv.svg +++ b/dev/man/bv.svg @@ -1,54 +1,54 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/man/energypressureplot.svg b/dev/man/energypressureplot.svg index 3e2a097..8ac6023 100644 --- a/dev/man/energypressureplot.svg +++ b/dev/man/energypressureplot.svg @@ -1,87 +1,92 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/man/eos.svg b/dev/man/eos.svg index b3e2dcb..fa1ddc3 100644 --- a/dev/man/eos.svg +++ b/dev/man/eos.svg @@ -1,52 +1,52 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/man/examples/index.html b/dev/man/examples/index.html index 049ddd0..5801d24 100644 --- a/dev/man/examples/index.html +++ b/dev/man/examples/index.html @@ -21,7 +21,7 @@ GKS: can't connect to GKS socket application GKS: Open failed in routine OPEN_WS -GKS: GKS not in proper state. GKS must be either in the state WSOP or WSAC in routine ACTIVATE_WS

Or, we can plot dual plots with energypressureplot:

julia> plot(; layout=(1, 2))Plot{Plots.GRBackend() n=0}
julia> energypressureplot(bm; label="Birch–Murnaghan");ERROR: BoundsError: attempt to access 1-element Vector{Plots.Subplot} at index [2]
julia> energypressureplot!(m; label="Murnaghan");
julia> energypressureplot!(pt; label="Poirier–Tarantola");
julia> energypressureplot!(v; label="Vinet");qt.qpa.xcb: could not connect to display 
+GKS: GKS not in proper state. GKS must be either in the state WSOP or WSAC in routine ACTIVATE_WS

Or, we can plot dual plots with energypressureplot:

julia> plot(; layout=(1, 2))Plot{Plots.GRBackend() n=0}
julia> energypressureplot!(bm; label="Birch–Murnaghan");
julia> energypressureplot!(m; label="Murnaghan");
julia> energypressureplot!(pt; label="Poirier–Tarantola");
julia> energypressureplot!(v; label="Vinet");qt.qpa.xcb: could not connect to display 
 qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
 This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
 
@@ -43,4 +43,4 @@
 GKS: can't connect to GKS socket application
 
 GKS: Open failed in routine OPEN_WS
-GKS: GKS not in proper state. GKS must be either in the state WSOP or WSAC in routine ACTIVATE_WS

+GKS: GKS not in proper state. GKS must be either in the state WSOP or WSAC in routine ACTIVATE_WS

diff --git a/dev/man/installation/index.html b/dev/man/installation/index.html index d85158a..56b021f 100644 --- a/dev/man/installation/index.html +++ b/dev/man/installation/index.html @@ -12,13 +12,13 @@ Updating git-repo `https://github.com/MineralsCloud/EquationOfStateRecipes.jl` Resolving package versions... Updating `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl/docs/Project.toml` - [8d49d7c9] ~ EquationOfStateRecipes v0.4.1 ⇒ v0.4.1 `https://github.com/MineralsCloud/EquationOfStateRecipes.jl#main` + [8d49d7c9] ~ EquationOfStateRecipes v0.4.1 ⇒ v0.5.0 `https://github.com/MineralsCloud/EquationOfStateRecipes.jl#main` Updating `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl/docs/Manifest.toml` - [8d49d7c9] ~ EquationOfStateRecipes v0.4.1 ⇒ v0.4.1 `https://github.com/MineralsCloud/EquationOfStateRecipes.jl#main` + [8d49d7c9] ~ EquationOfStateRecipes v0.4.1 ⇒ v0.5.0 `https://github.com/MineralsCloud/EquationOfStateRecipes.jl#main` Precompiling project... ✓ EquationOfStateRecipes ✓ EquationOfStateRecipes → PlotsExt - 2 dependencies successfully precompiled in 9 seconds. 180 already precompiled. + 2 dependencies successfully precompiled in 8 seconds. 180 already precompiled. 2 dependencies precompiled but different versions are currently loaded. Restart julia to access the new versions

in the second step above.

Update the package

Please watch our GitHub repository for new releases. Once we release a new version, you can update EquationOfStateRecipes by typing

julia> using Pkg
julia> Pkg.update("EquationOfStateRecipes")    Updating registry at `~/.julia/registries/General.toml`
     Updating git-repo `https://github.com/MineralsCloud/EquationOfStateRecipes.jl`
   No Changes to `~/work/EquationOfStateRecipes.jl/EquationOfStateRecipes.jl/docs/Project.toml`
@@ -29,4 +29,4 @@
 
 julia> Pkg.rm("EquationOfStateRecipes")
 
-julia> Pkg.gc()

  • Press Ctrl+D to quit the current session. Start a new Julia session and reinstall EquationOfStateRecipes.

    • +julia> Pkg.gc()

  • Press Ctrl+D to quit the current session. Start a new Julia session and reinstall EquationOfStateRecipes.

    • diff --git a/dev/man/troubleshooting/index.html b/dev/man/troubleshooting/index.html index f587333..b61290d 100644 --- a/dev/man/troubleshooting/index.html +++ b/dev/man/troubleshooting/index.html @@ -1,2 +1,2 @@ -Troubleshooting · EquationOfStateRecipes.jl
    Edit on GitHub

    Troubleshooting

    This page collects some possible errors you may encounter along with tips on how to fix them. If you have some questions about how to use this code, you are welcome to discuss with us.

    If you have additional tips, please either report an issue or submit a pull request with suggestions.

    Cannot find the Julia executable

    Make sure you have Julia installed in your environment. Please download the latest stable version for your platform. If you are using a *nix system, the recommended way is to use Juliaup. If you do not want to install Juliaup or you are using other platforms that Julia supports, download the corresponding binaries. Then, create a symbolic link to the Julia executable. If the path is not in your $PATH environment variable, export it to your $PATH.

    Some clusters, like Comet, or Expanse, already have Julia installed as a module, you may just module load julia to use it. If not, either install by yourself or contact your administrator.

    See Installation Guide for more information.

    Julia starts slow

    First, we recommend you download the latest version of Julia. Usually, the newest version has the best performance.

    If you need to use Julia for a simple, one-time task, you can start the Julia REPL with

    julia --compile=min

    to minimize compilation or

    julia --optimize=0

    to minimize optimizations, or just use both. Or you could make a system image and run with

    julia --sysimage custom-image.so

    See Fredrik Ekre's talk for details.

    +Troubleshooting · EquationOfStateRecipes.jl
    Edit on GitHub

    Troubleshooting

    This page collects some possible errors you may encounter along with tips on how to fix them. If you have some questions about how to use this code, you are welcome to discuss with us.

    If you have additional tips, please either report an issue or submit a pull request with suggestions.

    Cannot find the Julia executable

    Make sure you have Julia installed in your environment. Please download the latest stable version for your platform. If you are using a *nix system, the recommended way is to use Juliaup. If you do not want to install Juliaup or you are using other platforms that Julia supports, download the corresponding binaries. Then, create a symbolic link to the Julia executable. If the path is not in your $PATH environment variable, export it to your $PATH.

    Some clusters, like Comet, or Expanse, already have Julia installed as a module, you may just module load julia to use it. If not, either install by yourself or contact your administrator.

    See Installation Guide for more information.

    Julia starts slow

    First, we recommend you download the latest version of Julia. Usually, the newest version has the best performance.

    If you need to use Julia for a simple, one-time task, you can start the Julia REPL with

    julia --compile=min

    to minimize compilation or

    julia --optimize=0

    to minimize optimizations, or just use both. Or you could make a system image and run with

    julia --sysimage custom-image.so

    See Fredrik Ekre's talk for details.

    diff --git a/dev/man/units.svg b/dev/man/units.svg index eb19571..737e3da 100644 --- a/dev/man/units.svg +++ b/dev/man/units.svg @@ -1,92 +1,92 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/search/index.html b/dev/search/index.html index 354a59b..3849c8b 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · EquationOfStateRecipes.jl

    Loading search...

      +Search · EquationOfStateRecipes.jl

      Loading search...

        diff --git a/dev/search_index.js b/dev/search_index.js index 556484f..23b7ead 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"man/troubleshooting/#Troubleshooting","page":"Troubleshooting","title":"Troubleshooting","text":"","category":"section"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"Pages = [\"troubleshooting.md\"]\nDepth = 2","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"This page collects some possible errors you may encounter along with tips on how to fix them. If you have some questions about how to use this code, you are welcome to discuss with us.","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"If you have additional tips, please either report an issue or submit a pull request with suggestions.","category":"page"},{"location":"man/troubleshooting/#Cannot-find-the-Julia-executable","page":"Troubleshooting","title":"Cannot find the Julia executable","text":"","category":"section"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"Make sure you have Julia installed in your environment. Please download the latest stable version for your platform. If you are using a *nix system, the recommended way is to use Juliaup. If you do not want to install Juliaup or you are using other platforms that Julia supports, download the corresponding binaries. Then, create a symbolic link to the Julia executable. If the path is not in your $PATH environment variable, export it to your $PATH.","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"Some clusters, like Comet, or Expanse, already have Julia installed as a module, you may just module load julia to use it. If not, either install by yourself or contact your administrator.","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"See Installation Guide for more information.","category":"page"},{"location":"man/troubleshooting/#Julia-starts-slow","page":"Troubleshooting","title":"Julia starts slow","text":"","category":"section"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"First, we recommend you download the latest version of Julia. Usually, the newest version has the best performance.","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"If you need to use Julia for a simple, one-time task, you can start the Julia REPL with","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"julia --compile=min","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"to minimize compilation or","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"julia --optimize=0","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"to minimize optimizations, or just use both. Or you could make a system image and run with","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"julia --sysimage custom-image.so","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"See Fredrik Ekre's talk for details.","category":"page"},{"location":"developers/contributing/#Contributing","page":"Contributing","title":"Contributing","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Pages = [\"contributing.md\"]\nDepth = 2","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Welcome! This document explains some ways you can contribute to EquationOfStateRecipes.","category":"page"},{"location":"developers/contributing/#Code-of-conduct","page":"Contributing","title":"Code of conduct","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"This project and everyone participating in it is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.","category":"page"},{"location":"developers/contributing/#Join-the-community-forum","page":"Contributing","title":"Join the community forum","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"First up, join the community forum.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"The forum is a good place to ask questions about how to use EquationOfStateRecipes. You can also use the forum to discuss possible feature requests and bugs before raising a GitHub issue (more on this below).","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Aside from asking questions, the easiest way you can contribute to EquationOfStateRecipes is to help answer questions on the forum!","category":"page"},{"location":"developers/contributing/#Improve-the-documentation","page":"Contributing","title":"Improve the documentation","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Chances are, if you asked (or answered) a question on the community forum, then it is a sign that the documentation could be improved. Moreover, since it is your question, you are probably the best-placed person to improve it!","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"The docs are written in Markdown and are built using Documenter.jl. You can find the source of all the docs here.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"If your change is small (like fixing typos or one or two sentence corrections), the easiest way to do this is via GitHub's online editor. (GitHub has help on how to do this.)","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"If your change is larger or touches multiple files, you will need to make the change locally and then use Git to submit a pull request. (See Contribute code to EquationOfStateRecipes below for more on this.)","category":"page"},{"location":"developers/contributing/#File-a-bug-report","page":"Contributing","title":"File a bug report","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Another way to contribute to EquationOfStateRecipes is to file bug reports.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Make sure you read the info in the box where you write the body of the issue before posting. You can also find a copy of that info here.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nIf you're unsure whether you have a real bug, post on the community forum first. Someone will either help you fix the problem or let you know the most appropriate place to open a bug report.","category":"page"},{"location":"developers/contributing/#Contribute-code-to-EquationOfStateRecipes","page":"Contributing","title":"Contribute code to EquationOfStateRecipes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Finally, you can also contribute code to EquationOfStateRecipes!","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"warning: Warning\nIf you do not have experience with Git, GitHub, and Julia development, the first steps can be a little daunting. However, there are lots of tutorials available online, including:GitHub\nGit and GitHub\nGit\nJulia package development","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Once you are familiar with Git and GitHub, the workflow for contributing code to EquationOfStateRecipes is similar to the following:","category":"page"},{"location":"developers/contributing/#Step-1:-decide-what-to-work-on","page":"Contributing","title":"Step 1: decide what to work on","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"The first step is to find an open issue (or open a new one) for the problem you want to solve. Then, before spending too much time on it, discuss what you are planning to do in the issue to see if other contributors are fine with your proposed changes. Getting feedback early can improve code quality and avoid time spent writing code that does not get merged into EquationOfStateRecipes.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nAt this point, remember to be patient and polite; you may get a lot of comments on your issue! However, do not be afraid! Comments mean that people are willing to help you improve the code that you are contributing to EquationOfStateRecipes.","category":"page"},{"location":"developers/contributing/#Step-2:-fork-EquationOfStateRecipes","page":"Contributing","title":"Step 2: fork EquationOfStateRecipes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Go to https://github.com/MineralsCloud/EquationOfStateRecipes.jl and click the \"Fork\" button in the top-right corner. This will create a copy of EquationOfStateRecipes under your GitHub account.","category":"page"},{"location":"developers/contributing/#Step-3:-install-EquationOfStateRecipes-locally","page":"Contributing","title":"Step 3: install EquationOfStateRecipes locally","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Similar to Installation Guide, open the Julia REPL and run:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"using Pkg\nPkg.update()\nPkg.develop(\"EquationOfStateRecipes\")","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Then the package will be cloned to your local machine. On *nix systems, the default path is ~/.julia/dev/EquationOfStateRecipes unless you modify the JULIA_DEPOT_PATH environment variable. If you're on Windows, this will be C:\\\\Users\\\\\\\\.julia\\\\dev\\\\EquationOfStateRecipes. In the following text, we will call it PKGROOT.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Go to PKGROOT, start a new Julia session, and run","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"using Pkg\nPkg.instantiate()","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"to instantiate the project.","category":"page"},{"location":"developers/contributing/#Step-4:-checkout-a-new-branch","page":"Contributing","title":"Step 4: checkout a new branch","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"note: Note\nIn the following, replace any instance of GITHUB_ACCOUNT with your GitHub username.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"The next step is to check out a development branch. In a terminal (or command prompt on Windows), run:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"$ cd ~/.julia/dev/EquationOfStateRecipes\n\n$ git remote add GITHUB_ACCOUNT https://github.com/GITHUB_ACCOUNT/EquationOfStateRecipes.jl.git\n\n$ git checkout main\n\n$ git pull\n\n$ git checkout -b my_new_branch","category":"page"},{"location":"developers/contributing/#Step-5:-make-changes","page":"Contributing","title":"Step 5: make changes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Now make any changes to the source code inside the ~/.julia/dev/EquationOfStateRecipes directory.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Make sure you:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Follow our Style Guide and Run JuliaFormatter.\nAdd tests and documentation for any changes or new features.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nWhen you change the source code, you will need to restart Julia for the changes to take effect. If this is a pain, install Revise.jl.","category":"page"},{"location":"developers/contributing/#Step-6a:-test-your-code-changes","page":"Contributing","title":"Step 6a: test your code changes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"To test that your changes work, run the EquationOfStateRecipes test-suite by opening Julia and running:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"julia> cd(joinpath(DEPOT_PATH[1], \"dev\", \"EquationOfStateRecipes\"))\n\njulia> using Pkg\n\njulia> Pkg.activate(\".\")\n Activating new project at `~/.julia/dev/EquationOfStateRecipes`\n\njulia> Pkg.test()","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"warning: Warning\nRunning the tests might take a long time.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nIf you are using Revise.jl, you can also run the tests by calling include:include(\"test/runtests.jl\")This can be faster if you want to re-run the tests multiple times.","category":"page"},{"location":"developers/contributing/#Step-6b:-test-your-documentation-changes","page":"Contributing","title":"Step 6b: test your documentation changes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Open Julia, then run:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"julia> cd(joinpath(DEPOT_PATH[1], \"dev\", \"EquationOfStateRecipes\", \"docs\"))\n\njulia> using Pkg\n\njulia> Pkg.activate(\".\")\n Activating new project at `~/.julia/dev/EquationOfStateRecipes/docs`\n\njulia> include(\"src/make.jl\")","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"After a while, a folder PKGROOT/docs/build will appear. Open PKGROOT/docs/build/index.html with your favorite browser, and have fun!","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"warning: Warning\nBuilding the documentation might take a long time.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nIf there's a problem with the tests that you don't know how to fix, don't worry. Continue to step 5, and one of the EquationOfStateRecipes contributors will comment on your pull request, telling you how to fix things.","category":"page"},{"location":"developers/contributing/#Step-7:-make-a-pull-request","page":"Contributing","title":"Step 7: make a pull request","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Once you've made changes, you're ready to push the changes to GitHub. Run:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"$ cd ~/.julia/dev/EquationOfStateRecipes\n\n$ git add .\n\n$ git commit -m \"A descriptive message of the changes\"\n\n$ git push -u GITHUB_ACCOUNT my_new_branch","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Then go to our pull request page and follow the instructions that pop up to open a pull request.","category":"page"},{"location":"developers/contributing/#Step-8:-respond-to-comments","page":"Contributing","title":"Step 8: respond to comments","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"At this point, remember to be patient and polite; you may get a lot of comments on your pull request! However, do not be afraid! A lot of comments means that people are willing to help you improve the code that you are contributing to EquationOfStateRecipes.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"To respond to the comments, go back to step 5, make any changes, test the changes in step 6, and then make a new commit in step 7. Your PR will automatically update.","category":"page"},{"location":"developers/contributing/#Step-9:-cleaning-up","page":"Contributing","title":"Step 9: cleaning up","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Once the PR is merged, clean-up your Git repository, ready for the next contribution!","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"$ cd ~/.julia/dev/EquationOfStateRecipes\n\n$ git checkout main\n\n$ git pull","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"note: Note\nIf you have suggestions to improve this guide, please make a pull request! It's particularly helpful if you do this after your first pull request because you'll know all the parts that could be explained better.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Thanks for contributing to EquationOfStateRecipes!","category":"page"},{"location":"developers/design-principles/#Design-Principles","page":"Design Principles","title":"Design Principles","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Pages = [\"design-principles.md\"]\nDepth = 2","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"We adopt some SciML design guidelines here. Please read them before contributing!","category":"page"},{"location":"developers/design-principles/#Consistency-vs-adherence","page":"Design Principles","title":"Consistency vs adherence","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"According to PEP8:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.However, know when to be inconsistent—sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!","category":"page"},{"location":"developers/design-principles/#Community-contribution-guidelines","page":"Design Principles","title":"Community contribution guidelines","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"For a comprehensive set of community contribution guidelines, refer to ColPrac. A relevant point to highlight is that one PR should do one thing. In the context of style, this means that PRs which update the style of a package's code should not be mixed with fundamental code contributions. This separation makes it easier to ensure that large style improvement are isolated from substantive (and potentially breaking) code changes.","category":"page"},{"location":"developers/design-principles/#Open-source-contributions-are-allowed-to-start-small-and-grow-over-time","page":"Design Principles","title":"Open source contributions are allowed to start small and grow over time","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"If the standard for code contributions is that every PR needs to support every possible input type that anyone can think of, the barrier would be too high for newcomers. Instead, the principle is to be as correct as possible to begin with, and grow the generic support over time. All recommended functionality should be tested, any known generality issues should be documented in an issue (and with a @test_broken test when possible).","category":"page"},{"location":"developers/design-principles/#Generic-code-is-preferred-unless-code-is-known-to-be-specific","page":"Design Principles","title":"Generic code is preferred unless code is known to be specific","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"For example, the code:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"function f(A, B)\n for i in 1:length(A)\n A[i] = A[i] + B[i]\n end\nend","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"would not be preferred for two reasons. One is that it assumes A uses one-based indexing, which would fail in cases like OffsetArrays.jl and FFTViews.jl. Another issue is that it requires indexing, while not all array types support indexing (for example, CuArrays.jl). A more generic compatible implementation of this function would be to use broadcast, for example:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"function f(A, B)\n @. A = A + B\nend","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"which would allow support for a wider variety of array types.","category":"page"},{"location":"developers/design-principles/#Internal-types-should-match-the-types-used-by-users-when-possible","page":"Design Principles","title":"Internal types should match the types used by users when possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"If f(A) takes the input of some collections and computes an output from those collections, then it should be expected that if the user gives A as an Array, the computation should be done via Arrays. If A was a CuArray, then it should be expected that the computation should be internally done using a CuArray (or appropriately error if not supported). For these reasons, constructing arrays via generic methods, like similar(A), is preferred when writing f instead of using non-generic constructors like Array(undef,size(A)) unless the function is documented as being non-generic.","category":"page"},{"location":"developers/design-principles/#Trait-definition-and-adherence-to-generic-interface-is-preferred-when-possible","page":"Design Principles","title":"Trait definition and adherence to generic interface is preferred when possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Julia provides many interfaces, for example:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Iteration\nIndexing\nBroadcasting","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Those interfaces should be followed when possible. For example, when defining broadcast overloads, one should implement a BroadcastStyle as suggested by the documentation instead of simply attempting to bypass the broadcast system via copyto! overloads.","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"When interface functions are missing, these should be added to an interface package, like ArrayInterface.jl. Such traits should be declared and used when appropriate. For example, if a line of code requires mutation, the trait ArrayInterface.ismutable(A) should be checked before attempting to mutate, and informative error messages should be written to capture the immutable case (or, an alternative code which does not mutate should be given).","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"One example of this principle is demonstrated in the generation of Jacobian matrices. In many scientific applications, one may wish to generate a Jacobian cache from the user's input u0. A naive way to generate this Jacobian is J = similar(u0,length(u0),length(u0)). However, this will generate a Jacobian J such that J isa Matrix.","category":"page"},{"location":"developers/design-principles/#Macros-should-be-limited-and-only-be-used-for-syntactic-sugar","page":"Design Principles","title":"Macros should be limited and only be used for syntactic sugar","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Macros define new syntax, and for this reason they tend to be less composable than other coding styles and require prior familiarity to be easily understood. One principle to keep in mind is, \"can the person reading the code easily picture what code is being generated?\". For example, a user of Soss.jl may not know what code is being generated by:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"@model (x, α) begin\n σ ~ Exponential()\n β ~ Normal()\n y ~ For(x) do xj\n Normal(α + β * xj, σ)\n end\n return y\nend","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"and thus using such a macro as the interface is not preferred when possible. However, a macro like @muladd is trivial to picture on a code (it recursively transforms a*b + c to muladd(a,b,c) for more accuracy and efficiency), so using such a macro for example:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"julia> @macroexpand(@muladd k3 = f(t + c3 * dt, @. uprev + dt * (a031 * k1 + a032 * k2)))\n:(k3 = f((muladd)(c3, dt, t), (muladd).(dt, (muladd).(a032, k2, (*).(a031, k1)), uprev)))","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"is recommended. Some macros in this category are:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"@inbounds\n@muladd\n@view\n@named\n@.\n@..","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Some performance macros, like @simd, @threads, or @turbo from LoopVectorization.jl, make an exception in that their generated code may be foreign to many users. However, they still are classified as appropriate uses as they are syntactic sugar since they do (or should) not change the behavior of the program in measurable ways other than performance.","category":"page"},{"location":"developers/design-principles/#Errors-should-be-caught-as-early-as-possible,-and-error-messages-should-be-made-contextually-clear-for-newcomers","page":"Design Principles","title":"Errors should be caught as early as possible, and error messages should be made contextually clear for newcomers","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Whenever possible, defensive programming should be used to check for potential errors before they are encountered deeper within a package. For example, if one knows that f(u0,p) will error unless u0 is the size of p, this should be caught at the start of the function to throw a domain specific error, for example \"parameters and initial condition should be the same size\".","category":"page"},{"location":"developers/design-principles/#Subpackaging-and-interface-packages-is-preferred-over-conditional-modules-via-Requires.jl","page":"Design Principles","title":"Subpackaging and interface packages is preferred over conditional modules via Requires.jl","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Requires.jl should be avoided at all costs. If an interface package exists, such as ChainRulesCore.jl for defining automatic differentiation rules without requiring a dependency on the whole ChainRules.jl system, or RecipesBase.jl which allows for defining Plots.jl plot recipes without a dependency on Plots.jl, a direct dependency on these interface packages is preferred.","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Otherwise, instead of resorting to a conditional dependency using Requires.jl, it is preferred one creates subpackages, i.e. smaller independent packages kept within the same GitHub repository with independent versioning and package management. An example of this is seen in Optimization.jl which has subpackages like OptimizationBBO.jl for BlackBoxOptim.jl support.","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Some important interface packages to be aware of include:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"ChainRulesCore.jl\nRecipesBase.jl\nArrayInterface.jl\nCommonSolve.jl\nSciMLBase.jl","category":"page"},{"location":"developers/design-principles/#Functions-should-either-attempt-to-be-non-allocating-and-reuse-caches,-or-treat-inputs-as-immutable","page":"Design Principles","title":"Functions should either attempt to be non-allocating and reuse caches, or treat inputs as immutable","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Mutating codes and non-mutating codes fall into different worlds. When a code is fully immutable, the compiler can better reason about dependencies, optimize the code, and check for correctness. However, many times a code making the fullest use of mutation can outperform even what the best compilers of today can generate. That said, the worst of all worlds is when code mixes mutation with non-mutating code. Not only is this a mishmash of coding styles, it has the potential non-locality and compiler proof issues of mutating code while not fully benefiting from the mutation.","category":"page"},{"location":"developers/design-principles/#Out-of-place-and-immutability-is-preferred-when-sufficient-performant","page":"Design Principles","title":"Out-of-place and immutability is preferred when sufficient performant","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Mutation is used to get more performance by decreasing the amount of heap allocations. However, if it's not helpful for heap allocations in a given spot, do not use mutation. Mutation is scary and should be avoided unless it gives an immediate benefit. For example, if matrices are sufficiently large, then A*B is as fast as mul!(C,A,B), and thus writing A*B is preferred (unless the rest of the function is being careful about being fully non-allocating, in which case this should be mul! for consistency).","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Similarly, when defining types, using struct is preferred to mutable struct unless mutating the struct is a common occurrence. Even if mutating the struct is a common occurrence, see whether using Setfield.jl is sufficient. The compiler will optimize the construction of immutable structs, and thus this can be more efficient if it's not too much of a code hassle.","category":"page"},{"location":"developers/design-principles/#Tests-should-attempt-to-cover-a-wide-gamut-of-input-types","page":"Design Principles","title":"Tests should attempt to cover a wide gamut of input types","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Code coverage numbers are meaningless if one does not consider the input types. For example, one can hit all the code with Array, but that does not test whether CuArray is compatible! Thus, it's always good to think of coverage not in terms of lines of code but in terms of type coverage. A good list of number types to think about are:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Float64\nFloat32\nComplex\nDual\nBigFloat","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Array types to think about testing are:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Array\nOffsetArray\nCuArray","category":"page"},{"location":"developers/design-principles/#When-in-doubt,-a-submodule-should-become-a-subpackage-or-separate-package","page":"Design Principles","title":"When in doubt, a submodule should become a subpackage or separate package","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Each package should focus on one core idea. If there's something separate enough to be a submodule, could it instead be a separate well-tested and documented package to be used by other packages? Most likely yes.","category":"page"},{"location":"developers/design-principles/#Globals-should-be-avoided-whenever-possible","page":"Design Principles","title":"Globals should be avoided whenever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Global variables should be avoided whenever possible. When required, global variables should be constants and have an all uppercase name separated with underscores (e.g. MY_CONSTANT). They should be defined at the top of the file, immediately after imports and exports but before an __init__ function. If you truly want mutable global style behavior you may want to look into mutable containers.","category":"page"},{"location":"developers/design-principles/#Type-stable-and-type-grounded-code-is-preferred-wherever-possible","page":"Design Principles","title":"Type-stable and type-grounded code is preferred wherever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Type-stable and type-grounded code helps the compiler create not only more optimized code, but also faster to compile code. Always keep containers well-typed, functions specializing on the appropriate arguments, and types concrete.","category":"page"},{"location":"developers/design-principles/#Closures-should-be-avoided-whenever-possible","page":"Design Principles","title":"Closures should be avoided whenever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Closures can cause accidental type instabilities that are difficult to track down and debug; in the long run it saves time to always program defensively and avoid writing closures in the first place, even when a particular closure would not have been problematic. A similar argument applies to reading code with closures; if someone is looking for type instabilities, this is faster to do when code does not contain closures. See examples here.","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Furthermore, if you want to update variables in an outer scope, do so explicitly with Refs or self defined structs.","category":"page"},{"location":"developers/design-principles/#Numerical-functionality-should-use-the-appropriate-generic-numerical-interfaces","page":"Design Principles","title":"Numerical functionality should use the appropriate generic numerical interfaces","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"While you can use A\\b to do a linear solve inside a package, that does not mean that you should. This interface is only sufficient for performing factorizations, and so that limits the scaling choices, the types of A that can be supported, etc. Instead, linear solves within packages should use LinearSolve.jl. Similarly, nonlinear solves should use NonlinearSolve.jl. Optimization should use Optimization.jl. Etc. This allows the full generic choice to be given to the user without depending on every solver package (effectively recreating the generic interfaces within each package).","category":"page"},{"location":"developers/design-principles/#Functions-should-capture-one-underlying-principle","page":"Design Principles","title":"Functions should capture one underlying principle","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Functions mean one thing. Every dispatch of + should be \"the meaning of addition on these types\". While in theory you could add dispatches to + that mean something different, that will fail in generic code for which + means addition. Thus, for generic code to work, code needs to adhere to one meaning for each function. Every dispatch should be an instantiation of that meaning.","category":"page"},{"location":"developers/design-principles/#Internal-choices-should-be-exposed-as-options-whenever-possible","page":"Design Principles","title":"Internal choices should be exposed as options whenever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Whenever possible, numerical values and choices within scripts should be exposed as options to the user. This promotes code reusability beyond the few cases the author may have expected.","category":"page"},{"location":"developers/design-principles/#Prefer-code-reuse-over-rewrites-whenever-possible","page":"Design Principles","title":"Prefer code reuse over rewrites whenever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"If a package has a function you need, use the package. Add a dependency if you need to. If the function is missing a feature, prefer to add that feature to said package and then add it as a dependency. If the dependency is potentially troublesome, for example because it has a high load time, prefer to spend time helping said package fix these issues and add the dependency. Only when it does not seem possible to make the package \"good enough\" should using the package be abandoned. If it is abandoned, consider building a new package for this functionality as you need it, and then make it a dependency.","category":"page"},{"location":"developers/design-principles/#Prefer-to-not-shadow-functions","page":"Design Principles","title":"Prefer to not shadow functions","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"In Julia, two functions can share the same name if they belong to different namespaces. For example, X.f and Y.f can be two different functions, with different dispatches, but the same name. This should be avoided whenever possible. Instead of creating MyPackage.sort, consider adding dispatches to Base.sort for your types if these new dispatches match the underlying principle of the function. If they don't, it would be preferable to use a different name. While using MyPackage.sort is not conflicting, it is going to be confusing for most people unfamiliar with your code, so MyPackage.special_sort would be more helpful to newcomers reading the code.","category":"page"},{"location":"developers/style-guide/#style","page":"Style Guide","title":"Style Guide","text":"","category":"section"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"This section describes the coding style rules that apply to our code and that we recommend you to use it also.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"In some cases, our style guide diverges from Julia's official Style Guide (Please read it!). All such cases will be explicitly noted and justified.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"Our style guide adopts many recommendations from the BlueStyle. Please read the BlueStyle before contributing to this package. If these guidelines are not followed, your pull requests may not be accepted.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"info: Info\nThe style guide is always a work in progress, and not all EquationOfStateRecipes code follows the rules. When modifying EquationOfStateRecipes, please fix the style violations of the surrounding code (i.e., leave the code tidier than when you started). If large changes are needed, consider separating them into another pull request.","category":"page"},{"location":"developers/style-guide/#Formatting","page":"Style Guide","title":"Formatting","text":"","category":"section"},{"location":"developers/style-guide/#Run-JuliaFormatter","page":"Style Guide","title":"Run JuliaFormatter","text":"","category":"section"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"EquationOfStateRecipes uses JuliaFormatter as an auto-formatting tool.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"We use the options contained in .JuliaFormatter.toml.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"To format your code, cd to the EquationOfStateRecipes directory, then run:","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"julia> using Pkg\n\njulia> Pkg.add(\"JuliaFormatter\")\n\njulia> using JuliaFormatter: format\n\njulia> format(\"docs\"); format(\"src\"); format(\"test\")","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"info: Info\nA continuous integration check verifies that all PRs made to EquationOfStateRecipes have passed the formatter.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"The following sections outline extra style guide points that are not fixed automatically by JuliaFormatter.","category":"page"},{"location":"developers/style-guide/#Use-the-Julia-extension-for-Visual-Studio-Code","page":"Style Guide","title":"Use the Julia extension for Visual Studio Code","text":"","category":"section"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"Please use Visual Studio Code with the Julia extension to edit, format, and test your code. For the time being, we do not recommend using editors other than Visual Studio Code to edit your code.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"This extension already has JuliaFormatter integrated. So to format your code, follow the steps listed here.","category":"page"},{"location":"lib/public/#Public-API","page":"Public API","title":"Public API","text":"","category":"section"},{"location":"lib/public/#Contents","page":"Public API","title":"Contents","text":"","category":"section"},{"location":"lib/public/","page":"Public API","title":"Public API","text":"Pages = [\"public.md\"]\nDepth = 2","category":"page"},{"location":"lib/public/#Index","page":"Public API","title":"Index","text":"","category":"section"},{"location":"lib/public/","page":"Public API","title":"Public API","text":"Pages = [\"public.md\"]","category":"page"},{"location":"lib/public/#Public-interface","page":"Public API","title":"Public interface","text":"","category":"section"},{"location":"lib/public/","page":"Public API","title":"Public API","text":"For detailed examples, please refer to section \"Examples\".","category":"page"},{"location":"lib/public/","page":"Public API","title":"Public API","text":"plot\nenergyplot\npressureplot\nbulkmodulusplot\nenergypressureplot","category":"page"},{"location":"lib/public/#RecipesBase.plot","page":"Public API","title":"RecipesBase.plot","text":"plot(eos::EnergyEquation, volumes, args...; kw...)\nplot(eos::PressureEquation, volumes, args...; kw...)\nplot(eos::BulkModulusEquation, volumes, args...; kw...)\nplot!(eos::EnergyEquation, volumes, args...; kw...)\nplot!(eos::PressureEquation, volumes, args...; kw...)\nplot!(eos::BulkModulusEquation, volumes, args...; kw...)\nplot!(plotobj, eos::EnergyEquation, volumes, args...; kw...)\nplot!(plotobj, eos::PressureEquation, volumes, args...; kw...)\nplot!(plotobj, eos::BulkModulusEquation, volumes, args...; kw...)\n\nPlot the energy/pressure/bulk modulus versus volumes curve given an equation of state.\n\n\n\n\n\n","category":"function"},{"location":"lib/public/#EquationOfStateRecipes.energyplot","page":"Public API","title":"EquationOfStateRecipes.energyplot","text":"energyplot(params::Parameters, volumes, args...; kw...)\nenergyplot!(params::Parameters, volumes, args...; kw...)\nenergyplot!(plotobj, params::Parameters, volumes, args...; kw...)\n\nPlot the energy versus volumes curves given the parameters of equations of state.\n\n\n\n\n\n","category":"function"},{"location":"lib/public/#EquationOfStateRecipes.pressureplot","page":"Public API","title":"EquationOfStateRecipes.pressureplot","text":"pressureplot(params::Parameters, volumes, args...; kw...)\npressureplot!(params::Parameters, volumes, args...; kw...)\npressureplot!(plotobj, params::Parameters, volumes, args...; kw...)\n\nPlot the pressure versus volumes curves given the parameters of equations of state.\n\n\n\n\n\n","category":"function"},{"location":"lib/public/#EquationOfStateRecipes.bulkmodulusplot","page":"Public API","title":"EquationOfStateRecipes.bulkmodulusplot","text":"bulkmodulusplot(params::Parameters, volumes, args...; kw...)\nbulkmodulusplot!(params::Parameters, volumes, args...; kw...)\nbulkmodulusplot!(plotobj, params::Parameters, volumes, args...; kw...)\n\nPlot the bulk modulus versus volumes curves given the parameters of equations of state.\n\n\n\n\n\n","category":"function"},{"location":"lib/public/#EquationOfStateRecipes.energypressureplot","page":"Public API","title":"EquationOfStateRecipes.energypressureplot","text":"energypressureplot(params::Parameters, volumes, args...; layout=(1, 2), kw...)\nenergypressureplot!(params::Parameters, volumes, args...; layout=(1, 2), kw...)\nenergypressureplot!(plotobj, params::Parameters, volumes, args...; layout=(1, 2), kw...)\n\nCreate a graph that shows the energy/pressure versus volume curves using the given parameters of equations of state on the same horizontal axis.\n\nwarning: Warning\nTo use this function, you must specify the layout keyword argument as either (1, 2) or (2, 1)!\n\n\n\n\n\n","category":"function"},{"location":"#EquationOfStateRecipes","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Documentation for EquationOfStateRecipes.","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"See the Index for the complete list of documented functions and types.","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"The code, which is hosted on GitHub, is tested using various continuous integration services for its validity.","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"This repository is created and maintained by @singularitti, and contributions are highly welcome.","category":"page"},{"location":"#Package-features","page":"EquationOfStateRecipes","title":"Package features","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"This package contains recipes for EquationsOfStateOfSolids.jl which work with Plots.jl.","category":"page"},{"location":"#Installation","page":"EquationOfStateRecipes","title":"Installation","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"The package can be installed with the Julia package manager. From the Julia REPL, type ] to enter the Pkg mode and run:","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"pkg> add EquationOfStateRecipes","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Or, equivalently, via Pkg.jl:","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"import Pkg; Pkg.add(\"EquationOfStateRecipes\")","category":"page"},{"location":"#Documentation","page":"EquationOfStateRecipes","title":"Documentation","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"STABLE — documentation of the most recently tagged version.\nDEV — documentation of the in-development version.","category":"page"},{"location":"#Project-status","page":"EquationOfStateRecipes","title":"Project status","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"The package is developed for and tested against Julia v1.6 and above on Linux, macOS, and Windows.","category":"page"},{"location":"#Questions-and-contributions","page":"EquationOfStateRecipes","title":"Questions and contributions","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"You can post usage questions on our discussion page.","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"We welcome contributions, feature requests, and suggestions. If you encounter any problems, please open an issue. The Contributing page has a few guidelines that should be followed when opening pull requests and contributing code.","category":"page"},{"location":"#Manual-outline","page":"EquationOfStateRecipes","title":"Manual outline","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Pages = [\n \"man/installation.md\",\n \"man/examples.md\",\n \"man/troubleshooting.md\",\n \"developers/contributing.md\",\n \"developers/style-guide.md\",\n \"developers/design-principles.md\",\n]\nDepth = 3","category":"page"},{"location":"#Library-outline","page":"EquationOfStateRecipes","title":"Library outline","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Pages = [\"lib/public.md\", \"lib/internals.md\"]","category":"page"},{"location":"#main-index","page":"EquationOfStateRecipes","title":"Index","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Pages = [\"lib/public.md\"]","category":"page"},{"location":"man/examples/#Examples","page":"Examples","title":"Examples","text":"","category":"section"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Pages = [\"examples.md\"]\nDepth = 2","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Here is an example of plotting four equations of state in one figure with energy and pressure versus volume.","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"We can plot these parameters directly using shorthand functions such as energyplot, pressureplot, bulkmodulusplot:","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"using EquationOfStateRecipes\nusing EquationsOfStateOfSolids\nusing Plots\n\nbm = BirchMurnaghan3rd(40.989265727926536, 0.5369258245609575, 4.178644231927682, -10.8428039082991);\nm = Murnaghan1st(41.13757924604193, 0.5144967654094419, 3.9123863221667086, -10.836794510844241);\npt = PoirierTarantola3rd(40.86770643567071, 0.5667729960008748, 4.331688934947504, -10.851486685029437);\nv = Vinet(40.9168756740098, 0.5493839427843088, 4.3051929493806345, -10.846160810983498);\n\nplot(; legend=true);\nbulkmodulusplot!(bm; label=\"Birch–Murnaghan\");\nbulkmodulusplot!(bm; label=\"Murnaghan\");\nbulkmodulusplot!(pt; label=\"Poirier–Tarantola\");\nbulkmodulusplot!(v; label=\"Vinet\");\ntitle!(raw\"$B(V)$\");\nsavefig(\"bv.svg\"); nothing # hide","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"(Image: )","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Of course, we can construct four equations of state from those parameters and plot them:","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"bmeos = EnergyEquation(bm);\nmeos = EnergyEquation(m);\npteos = EnergyEquation(pt);\nveos = EnergyEquation(v);\n\nplot(; legend=true);\nplot!(bmeos; label=\"Birch–Murnaghan\");\nplot!(meos; label=\"Murnaghan\");\nplot!(pteos; label=\"Poirier–Tarantola\");\nplot!(veos; label=\"Vinet\");\ntitle!(raw\"$E(V)$\");\nsavefig(\"eos.svg\"); nothing # hide","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"(Image: )","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Or, we can plot dual plots with energypressureplot:","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"plot(; layout=(1, 2))\nenergypressureplot(bm; label=\"Birch–Murnaghan\");\nenergypressureplot!(m; label=\"Murnaghan\");\nenergypressureplot!(pt; label=\"Poirier–Tarantola\");\nenergypressureplot!(v; label=\"Vinet\");\nsavefig(\"energypressureplot.svg\"); nothing # hide","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"(Image: )","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Also, we can add units to these equations of state without any difficulty:","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"using Unitful, UnitfulAtomic\n\nbm = BirchMurnaghan3rd(40.989265727926536u\"angstrom^3\", 0.5369258245609575u\"Ry/angstrom^3\", 4.178644231927682, -10.8428039082991u\"Ry\");\nm = Murnaghan1st(41.13757924604193u\"angstrom^3\", 0.5144967654094419u\"Ry/angstrom^3\", 3.9123863221667086, -10.836794510844241u\"Ry\");\npt = PoirierTarantola3rd(40.86770643567071u\"angstrom^3\", 0.5667729960008748u\"Ry/angstrom^3\", 4.331688934947504, -10.851486685029437u\"Ry\");\nv = Vinet(40.9168756740098u\"angstrom^3\", 0.5493839427843088u\"Ry/angstrom^3\", 4.3051929493806345, -10.846160810983498u\"Ry\");\n\nenergypressureplot(bm; label=\"Birch–Murnaghan\", layout=(2, 1));\nenergypressureplot!(m; label=\"Murnaghan\");\nenergypressureplot!(pt; label=\"Poirier–Tarantola\");\nenergypressureplot!(v; label=\"Vinet\");\nsavefig(\"units.svg\"); nothing # hide","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"(Image: )","category":"page"},{"location":"man/installation/#Installation-Guide","page":"Installation Guide","title":"Installation Guide","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Pages = [\"installation.md\"]\nDepth = 2","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Here are the installation instructions for package EquationOfStateRecipes. If you have trouble installing it, please refer to our Troubleshooting page for more information.","category":"page"},{"location":"man/installation/#Install-Julia","page":"Installation Guide","title":"Install Julia","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"First, you should install Julia. We recommend downloading it from its official website. Please follow the detailed instructions on its website if you have to build Julia from source. Some computing centers provide preinstalled Julia. Please contact your administrator for more information in that case. Here's some additional information on how to set up Julia on HPC clusters.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"If you have Homebrew installed, open the Terminal app and type","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"brew install julia","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"to install it as a formula.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"If you are also using macOS and want to install it as a prebuilt binary app, type","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"brew install --cask julia","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"instead.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"If you want to install multiple Julia versions in the same operating system, a recommended way is to use a version manager such as Juliaup. First, install Juliaup. Then, run","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"juliaup add release\njuliaup default release","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"to configure the julia command to start the latest stable version of Julia (this is also the default value).","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Here is a short video introduction to Juliaup made by its authors.","category":"page"},{"location":"man/installation/#Which-version-should-I-pick?","page":"Installation Guide","title":"Which version should I pick?","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"You can install the current stable release or the long-term support (LTS) release.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"The current stable release is the latest release of Julia. It has access to newer features, and is likely faster.\nThe long-term support release is an older version of Julia that has continued to receive bug and security fixes. However, it may not have the latest features or performance improvements.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"For most users, you should install the current stable release, and whenever Julia releases a new version of the current stable release, you should update your version of Julia. Note that any code you write on one version of the current stable release will continue to work on all subsequent releases.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"For users in restricted software environments (e.g., your enterprise IT controls what software you can install), you may be better off installing the long-term support release because you will not have to update Julia as frequently.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Versions above v1.3, especially the latest stable ones, are strongly recommended. This package is highly unlikely to work on v1.0 and earlier versions. Since the Julia team has set v1.6 as the LTS release, we will gradually drop support for versions below v1.6.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Julia and Julia packages support multiple operating systems and CPU architectures; check this table to see if it can be installed on your machine. For Mac computers with M-series processors, this package and its dependencies may not work. Please install the Intel-compatible version of Julia (for macOS x86-64) if any platform-related error occurs.","category":"page"},{"location":"man/installation/#Install-the-package","page":"Installation Guide","title":"Install the package","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Now I am using macOS as a standard platform to explain the following steps:","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Open the Terminal app, and type julia to start an interactive session (known as the REPL).\nRun the following commands and wait for them to finish:\njulia> using Pkg\n\njulia> Pkg.update()\n\njulia> Pkg.add(\"EquationOfStateRecipes\")\nRun\njulia> using EquationOfStateRecipes\nand have fun!\nPlease keep the Julia session active while using it. Restarting the session may take some time.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"If you want to install the latest in-development (probably buggy) version of EquationOfStateRecipes, type","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"using Pkg\nPkg.update()\npkg\"add https://github.com/MineralsCloud/EquationOfStateRecipes.jl\"","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"in the second step above.","category":"page"},{"location":"man/installation/#Update-the-package","page":"Installation Guide","title":"Update the package","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Please watch our GitHub repository for new releases. Once we release a new version, you can update EquationOfStateRecipes by typing","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"using Pkg\nPkg.update(\"EquationOfStateRecipes\")\nPkg.gc()","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"in the Julia REPL.","category":"page"},{"location":"man/installation/#Uninstall-and-then-reinstall-the-package","page":"Installation Guide","title":"Uninstall and then reinstall the package","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Sometimes errors may occur if the package is not properly installed. In this case, you may want to uninstall and reinstall the package. Here is how to do that:","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"To uninstall, in a Julia session, run\njulia> using Pkg\n\njulia> Pkg.rm(\"EquationOfStateRecipes\")\n\njulia> Pkg.gc()\nPress Ctrl+D to quit the current session. Start a new Julia session and reinstall EquationOfStateRecipes.","category":"page"}] +[{"location":"man/troubleshooting/#Troubleshooting","page":"Troubleshooting","title":"Troubleshooting","text":"","category":"section"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"Pages = [\"troubleshooting.md\"]\nDepth = 2","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"This page collects some possible errors you may encounter along with tips on how to fix them. If you have some questions about how to use this code, you are welcome to discuss with us.","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"If you have additional tips, please either report an issue or submit a pull request with suggestions.","category":"page"},{"location":"man/troubleshooting/#Cannot-find-the-Julia-executable","page":"Troubleshooting","title":"Cannot find the Julia executable","text":"","category":"section"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"Make sure you have Julia installed in your environment. Please download the latest stable version for your platform. If you are using a *nix system, the recommended way is to use Juliaup. If you do not want to install Juliaup or you are using other platforms that Julia supports, download the corresponding binaries. Then, create a symbolic link to the Julia executable. If the path is not in your $PATH environment variable, export it to your $PATH.","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"Some clusters, like Comet, or Expanse, already have Julia installed as a module, you may just module load julia to use it. If not, either install by yourself or contact your administrator.","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"See Installation Guide for more information.","category":"page"},{"location":"man/troubleshooting/#Julia-starts-slow","page":"Troubleshooting","title":"Julia starts slow","text":"","category":"section"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"First, we recommend you download the latest version of Julia. Usually, the newest version has the best performance.","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"If you need to use Julia for a simple, one-time task, you can start the Julia REPL with","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"julia --compile=min","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"to minimize compilation or","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"julia --optimize=0","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"to minimize optimizations, or just use both. Or you could make a system image and run with","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"julia --sysimage custom-image.so","category":"page"},{"location":"man/troubleshooting/","page":"Troubleshooting","title":"Troubleshooting","text":"See Fredrik Ekre's talk for details.","category":"page"},{"location":"developers/contributing/#Contributing","page":"Contributing","title":"Contributing","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Pages = [\"contributing.md\"]\nDepth = 2","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Welcome! This document explains some ways you can contribute to EquationOfStateRecipes.","category":"page"},{"location":"developers/contributing/#Code-of-conduct","page":"Contributing","title":"Code of conduct","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"This project and everyone participating in it is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.","category":"page"},{"location":"developers/contributing/#Join-the-community-forum","page":"Contributing","title":"Join the community forum","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"First up, join the community forum.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"The forum is a good place to ask questions about how to use EquationOfStateRecipes. You can also use the forum to discuss possible feature requests and bugs before raising a GitHub issue (more on this below).","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Aside from asking questions, the easiest way you can contribute to EquationOfStateRecipes is to help answer questions on the forum!","category":"page"},{"location":"developers/contributing/#Improve-the-documentation","page":"Contributing","title":"Improve the documentation","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Chances are, if you asked (or answered) a question on the community forum, then it is a sign that the documentation could be improved. Moreover, since it is your question, you are probably the best-placed person to improve it!","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"The docs are written in Markdown and are built using Documenter.jl. You can find the source of all the docs here.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"If your change is small (like fixing typos or one or two sentence corrections), the easiest way to do this is via GitHub's online editor. (GitHub has help on how to do this.)","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"If your change is larger or touches multiple files, you will need to make the change locally and then use Git to submit a pull request. (See Contribute code to EquationOfStateRecipes below for more on this.)","category":"page"},{"location":"developers/contributing/#File-a-bug-report","page":"Contributing","title":"File a bug report","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Another way to contribute to EquationOfStateRecipes is to file bug reports.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Make sure you read the info in the box where you write the body of the issue before posting. You can also find a copy of that info here.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nIf you're unsure whether you have a real bug, post on the community forum first. Someone will either help you fix the problem or let you know the most appropriate place to open a bug report.","category":"page"},{"location":"developers/contributing/#Contribute-code-to-EquationOfStateRecipes","page":"Contributing","title":"Contribute code to EquationOfStateRecipes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Finally, you can also contribute code to EquationOfStateRecipes!","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"warning: Warning\nIf you do not have experience with Git, GitHub, and Julia development, the first steps can be a little daunting. However, there are lots of tutorials available online, including:GitHub\nGit and GitHub\nGit\nJulia package development","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Once you are familiar with Git and GitHub, the workflow for contributing code to EquationOfStateRecipes is similar to the following:","category":"page"},{"location":"developers/contributing/#Step-1:-decide-what-to-work-on","page":"Contributing","title":"Step 1: decide what to work on","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"The first step is to find an open issue (or open a new one) for the problem you want to solve. Then, before spending too much time on it, discuss what you are planning to do in the issue to see if other contributors are fine with your proposed changes. Getting feedback early can improve code quality and avoid time spent writing code that does not get merged into EquationOfStateRecipes.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nAt this point, remember to be patient and polite; you may get a lot of comments on your issue! However, do not be afraid! Comments mean that people are willing to help you improve the code that you are contributing to EquationOfStateRecipes.","category":"page"},{"location":"developers/contributing/#Step-2:-fork-EquationOfStateRecipes","page":"Contributing","title":"Step 2: fork EquationOfStateRecipes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Go to https://github.com/MineralsCloud/EquationOfStateRecipes.jl and click the \"Fork\" button in the top-right corner. This will create a copy of EquationOfStateRecipes under your GitHub account.","category":"page"},{"location":"developers/contributing/#Step-3:-install-EquationOfStateRecipes-locally","page":"Contributing","title":"Step 3: install EquationOfStateRecipes locally","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Similar to Installation Guide, open the Julia REPL and run:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"using Pkg\nPkg.update()\nPkg.develop(\"EquationOfStateRecipes\")","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Then the package will be cloned to your local machine. On *nix systems, the default path is ~/.julia/dev/EquationOfStateRecipes unless you modify the JULIA_DEPOT_PATH environment variable. If you're on Windows, this will be C:\\\\Users\\\\\\\\.julia\\\\dev\\\\EquationOfStateRecipes. In the following text, we will call it PKGROOT.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Go to PKGROOT, start a new Julia session, and run","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"using Pkg\nPkg.instantiate()","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"to instantiate the project.","category":"page"},{"location":"developers/contributing/#Step-4:-checkout-a-new-branch","page":"Contributing","title":"Step 4: checkout a new branch","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"note: Note\nIn the following, replace any instance of GITHUB_ACCOUNT with your GitHub username.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"The next step is to check out a development branch. In a terminal (or command prompt on Windows), run:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"$ cd ~/.julia/dev/EquationOfStateRecipes\n\n$ git remote add GITHUB_ACCOUNT https://github.com/GITHUB_ACCOUNT/EquationOfStateRecipes.jl.git\n\n$ git checkout main\n\n$ git pull\n\n$ git checkout -b my_new_branch","category":"page"},{"location":"developers/contributing/#Step-5:-make-changes","page":"Contributing","title":"Step 5: make changes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Now make any changes to the source code inside the ~/.julia/dev/EquationOfStateRecipes directory.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Make sure you:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Follow our Style Guide and Run JuliaFormatter.\nAdd tests and documentation for any changes or new features.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nWhen you change the source code, you will need to restart Julia for the changes to take effect. If this is a pain, install Revise.jl.","category":"page"},{"location":"developers/contributing/#Step-6a:-test-your-code-changes","page":"Contributing","title":"Step 6a: test your code changes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"To test that your changes work, run the EquationOfStateRecipes test-suite by opening Julia and running:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"julia> cd(joinpath(DEPOT_PATH[1], \"dev\", \"EquationOfStateRecipes\"))\n\njulia> using Pkg\n\njulia> Pkg.activate(\".\")\n Activating new project at `~/.julia/dev/EquationOfStateRecipes`\n\njulia> Pkg.test()","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"warning: Warning\nRunning the tests might take a long time.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nIf you are using Revise.jl, you can also run the tests by calling include:include(\"test/runtests.jl\")This can be faster if you want to re-run the tests multiple times.","category":"page"},{"location":"developers/contributing/#Step-6b:-test-your-documentation-changes","page":"Contributing","title":"Step 6b: test your documentation changes","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Open Julia, then run:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"julia> cd(joinpath(DEPOT_PATH[1], \"dev\", \"EquationOfStateRecipes\", \"docs\"))\n\njulia> using Pkg\n\njulia> Pkg.activate(\".\")\n Activating new project at `~/.julia/dev/EquationOfStateRecipes/docs`\n\njulia> include(\"src/make.jl\")","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"After a while, a folder PKGROOT/docs/build will appear. Open PKGROOT/docs/build/index.html with your favorite browser, and have fun!","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"warning: Warning\nBuilding the documentation might take a long time.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"tip: Tip\nIf there's a problem with the tests that you don't know how to fix, don't worry. Continue to step 5, and one of the EquationOfStateRecipes contributors will comment on your pull request, telling you how to fix things.","category":"page"},{"location":"developers/contributing/#Step-7:-make-a-pull-request","page":"Contributing","title":"Step 7: make a pull request","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Once you've made changes, you're ready to push the changes to GitHub. Run:","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"$ cd ~/.julia/dev/EquationOfStateRecipes\n\n$ git add .\n\n$ git commit -m \"A descriptive message of the changes\"\n\n$ git push -u GITHUB_ACCOUNT my_new_branch","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Then go to our pull request page and follow the instructions that pop up to open a pull request.","category":"page"},{"location":"developers/contributing/#Step-8:-respond-to-comments","page":"Contributing","title":"Step 8: respond to comments","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"At this point, remember to be patient and polite; you may get a lot of comments on your pull request! However, do not be afraid! A lot of comments means that people are willing to help you improve the code that you are contributing to EquationOfStateRecipes.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"To respond to the comments, go back to step 5, make any changes, test the changes in step 6, and then make a new commit in step 7. Your PR will automatically update.","category":"page"},{"location":"developers/contributing/#Step-9:-cleaning-up","page":"Contributing","title":"Step 9: cleaning up","text":"","category":"section"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Once the PR is merged, clean-up your Git repository, ready for the next contribution!","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"$ cd ~/.julia/dev/EquationOfStateRecipes\n\n$ git checkout main\n\n$ git pull","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"note: Note\nIf you have suggestions to improve this guide, please make a pull request! It's particularly helpful if you do this after your first pull request because you'll know all the parts that could be explained better.","category":"page"},{"location":"developers/contributing/","page":"Contributing","title":"Contributing","text":"Thanks for contributing to EquationOfStateRecipes!","category":"page"},{"location":"developers/design-principles/#Design-Principles","page":"Design Principles","title":"Design Principles","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Pages = [\"design-principles.md\"]\nDepth = 2","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"We adopt some SciML design guidelines here. Please read them before contributing!","category":"page"},{"location":"developers/design-principles/#Consistency-vs-adherence","page":"Design Principles","title":"Consistency vs adherence","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"According to PEP8:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.However, know when to be inconsistent—sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!","category":"page"},{"location":"developers/design-principles/#Community-contribution-guidelines","page":"Design Principles","title":"Community contribution guidelines","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"For a comprehensive set of community contribution guidelines, refer to ColPrac. A relevant point to highlight is that one PR should do one thing. In the context of style, this means that PRs which update the style of a package's code should not be mixed with fundamental code contributions. This separation makes it easier to ensure that large style improvement are isolated from substantive (and potentially breaking) code changes.","category":"page"},{"location":"developers/design-principles/#Open-source-contributions-are-allowed-to-start-small-and-grow-over-time","page":"Design Principles","title":"Open source contributions are allowed to start small and grow over time","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"If the standard for code contributions is that every PR needs to support every possible input type that anyone can think of, the barrier would be too high for newcomers. Instead, the principle is to be as correct as possible to begin with, and grow the generic support over time. All recommended functionality should be tested, any known generality issues should be documented in an issue (and with a @test_broken test when possible).","category":"page"},{"location":"developers/design-principles/#Generic-code-is-preferred-unless-code-is-known-to-be-specific","page":"Design Principles","title":"Generic code is preferred unless code is known to be specific","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"For example, the code:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"function f(A, B)\n for i in 1:length(A)\n A[i] = A[i] + B[i]\n end\nend","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"would not be preferred for two reasons. One is that it assumes A uses one-based indexing, which would fail in cases like OffsetArrays.jl and FFTViews.jl. Another issue is that it requires indexing, while not all array types support indexing (for example, CuArrays.jl). A more generic compatible implementation of this function would be to use broadcast, for example:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"function f(A, B)\n @. A = A + B\nend","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"which would allow support for a wider variety of array types.","category":"page"},{"location":"developers/design-principles/#Internal-types-should-match-the-types-used-by-users-when-possible","page":"Design Principles","title":"Internal types should match the types used by users when possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"If f(A) takes the input of some collections and computes an output from those collections, then it should be expected that if the user gives A as an Array, the computation should be done via Arrays. If A was a CuArray, then it should be expected that the computation should be internally done using a CuArray (or appropriately error if not supported). For these reasons, constructing arrays via generic methods, like similar(A), is preferred when writing f instead of using non-generic constructors like Array(undef,size(A)) unless the function is documented as being non-generic.","category":"page"},{"location":"developers/design-principles/#Trait-definition-and-adherence-to-generic-interface-is-preferred-when-possible","page":"Design Principles","title":"Trait definition and adherence to generic interface is preferred when possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Julia provides many interfaces, for example:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Iteration\nIndexing\nBroadcasting","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Those interfaces should be followed when possible. For example, when defining broadcast overloads, one should implement a BroadcastStyle as suggested by the documentation instead of simply attempting to bypass the broadcast system via copyto! overloads.","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"When interface functions are missing, these should be added to an interface package, like ArrayInterface.jl. Such traits should be declared and used when appropriate. For example, if a line of code requires mutation, the trait ArrayInterface.ismutable(A) should be checked before attempting to mutate, and informative error messages should be written to capture the immutable case (or, an alternative code which does not mutate should be given).","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"One example of this principle is demonstrated in the generation of Jacobian matrices. In many scientific applications, one may wish to generate a Jacobian cache from the user's input u0. A naive way to generate this Jacobian is J = similar(u0,length(u0),length(u0)). However, this will generate a Jacobian J such that J isa Matrix.","category":"page"},{"location":"developers/design-principles/#Macros-should-be-limited-and-only-be-used-for-syntactic-sugar","page":"Design Principles","title":"Macros should be limited and only be used for syntactic sugar","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Macros define new syntax, and for this reason they tend to be less composable than other coding styles and require prior familiarity to be easily understood. One principle to keep in mind is, \"can the person reading the code easily picture what code is being generated?\". For example, a user of Soss.jl may not know what code is being generated by:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"@model (x, α) begin\n σ ~ Exponential()\n β ~ Normal()\n y ~ For(x) do xj\n Normal(α + β * xj, σ)\n end\n return y\nend","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"and thus using such a macro as the interface is not preferred when possible. However, a macro like @muladd is trivial to picture on a code (it recursively transforms a*b + c to muladd(a,b,c) for more accuracy and efficiency), so using such a macro for example:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"julia> @macroexpand(@muladd k3 = f(t + c3 * dt, @. uprev + dt * (a031 * k1 + a032 * k2)))\n:(k3 = f((muladd)(c3, dt, t), (muladd).(dt, (muladd).(a032, k2, (*).(a031, k1)), uprev)))","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"is recommended. Some macros in this category are:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"@inbounds\n@muladd\n@view\n@named\n@.\n@..","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Some performance macros, like @simd, @threads, or @turbo from LoopVectorization.jl, make an exception in that their generated code may be foreign to many users. However, they still are classified as appropriate uses as they are syntactic sugar since they do (or should) not change the behavior of the program in measurable ways other than performance.","category":"page"},{"location":"developers/design-principles/#Errors-should-be-caught-as-early-as-possible,-and-error-messages-should-be-made-contextually-clear-for-newcomers","page":"Design Principles","title":"Errors should be caught as early as possible, and error messages should be made contextually clear for newcomers","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Whenever possible, defensive programming should be used to check for potential errors before they are encountered deeper within a package. For example, if one knows that f(u0,p) will error unless u0 is the size of p, this should be caught at the start of the function to throw a domain specific error, for example \"parameters and initial condition should be the same size\".","category":"page"},{"location":"developers/design-principles/#Subpackaging-and-interface-packages-is-preferred-over-conditional-modules-via-Requires.jl","page":"Design Principles","title":"Subpackaging and interface packages is preferred over conditional modules via Requires.jl","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Requires.jl should be avoided at all costs. If an interface package exists, such as ChainRulesCore.jl for defining automatic differentiation rules without requiring a dependency on the whole ChainRules.jl system, or RecipesBase.jl which allows for defining Plots.jl plot recipes without a dependency on Plots.jl, a direct dependency on these interface packages is preferred.","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Otherwise, instead of resorting to a conditional dependency using Requires.jl, it is preferred one creates subpackages, i.e. smaller independent packages kept within the same GitHub repository with independent versioning and package management. An example of this is seen in Optimization.jl which has subpackages like OptimizationBBO.jl for BlackBoxOptim.jl support.","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Some important interface packages to be aware of include:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"ChainRulesCore.jl\nRecipesBase.jl\nArrayInterface.jl\nCommonSolve.jl\nSciMLBase.jl","category":"page"},{"location":"developers/design-principles/#Functions-should-either-attempt-to-be-non-allocating-and-reuse-caches,-or-treat-inputs-as-immutable","page":"Design Principles","title":"Functions should either attempt to be non-allocating and reuse caches, or treat inputs as immutable","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Mutating codes and non-mutating codes fall into different worlds. When a code is fully immutable, the compiler can better reason about dependencies, optimize the code, and check for correctness. However, many times a code making the fullest use of mutation can outperform even what the best compilers of today can generate. That said, the worst of all worlds is when code mixes mutation with non-mutating code. Not only is this a mishmash of coding styles, it has the potential non-locality and compiler proof issues of mutating code while not fully benefiting from the mutation.","category":"page"},{"location":"developers/design-principles/#Out-of-place-and-immutability-is-preferred-when-sufficient-performant","page":"Design Principles","title":"Out-of-place and immutability is preferred when sufficient performant","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Mutation is used to get more performance by decreasing the amount of heap allocations. However, if it's not helpful for heap allocations in a given spot, do not use mutation. Mutation is scary and should be avoided unless it gives an immediate benefit. For example, if matrices are sufficiently large, then A*B is as fast as mul!(C,A,B), and thus writing A*B is preferred (unless the rest of the function is being careful about being fully non-allocating, in which case this should be mul! for consistency).","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Similarly, when defining types, using struct is preferred to mutable struct unless mutating the struct is a common occurrence. Even if mutating the struct is a common occurrence, see whether using Setfield.jl is sufficient. The compiler will optimize the construction of immutable structs, and thus this can be more efficient if it's not too much of a code hassle.","category":"page"},{"location":"developers/design-principles/#Tests-should-attempt-to-cover-a-wide-gamut-of-input-types","page":"Design Principles","title":"Tests should attempt to cover a wide gamut of input types","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Code coverage numbers are meaningless if one does not consider the input types. For example, one can hit all the code with Array, but that does not test whether CuArray is compatible! Thus, it's always good to think of coverage not in terms of lines of code but in terms of type coverage. A good list of number types to think about are:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Float64\nFloat32\nComplex\nDual\nBigFloat","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Array types to think about testing are:","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Array\nOffsetArray\nCuArray","category":"page"},{"location":"developers/design-principles/#When-in-doubt,-a-submodule-should-become-a-subpackage-or-separate-package","page":"Design Principles","title":"When in doubt, a submodule should become a subpackage or separate package","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Each package should focus on one core idea. If there's something separate enough to be a submodule, could it instead be a separate well-tested and documented package to be used by other packages? Most likely yes.","category":"page"},{"location":"developers/design-principles/#Globals-should-be-avoided-whenever-possible","page":"Design Principles","title":"Globals should be avoided whenever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Global variables should be avoided whenever possible. When required, global variables should be constants and have an all uppercase name separated with underscores (e.g. MY_CONSTANT). They should be defined at the top of the file, immediately after imports and exports but before an __init__ function. If you truly want mutable global style behavior you may want to look into mutable containers.","category":"page"},{"location":"developers/design-principles/#Type-stable-and-type-grounded-code-is-preferred-wherever-possible","page":"Design Principles","title":"Type-stable and type-grounded code is preferred wherever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Type-stable and type-grounded code helps the compiler create not only more optimized code, but also faster to compile code. Always keep containers well-typed, functions specializing on the appropriate arguments, and types concrete.","category":"page"},{"location":"developers/design-principles/#Closures-should-be-avoided-whenever-possible","page":"Design Principles","title":"Closures should be avoided whenever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Closures can cause accidental type instabilities that are difficult to track down and debug; in the long run it saves time to always program defensively and avoid writing closures in the first place, even when a particular closure would not have been problematic. A similar argument applies to reading code with closures; if someone is looking for type instabilities, this is faster to do when code does not contain closures. See examples here.","category":"page"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Furthermore, if you want to update variables in an outer scope, do so explicitly with Refs or self defined structs.","category":"page"},{"location":"developers/design-principles/#Numerical-functionality-should-use-the-appropriate-generic-numerical-interfaces","page":"Design Principles","title":"Numerical functionality should use the appropriate generic numerical interfaces","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"While you can use A\\b to do a linear solve inside a package, that does not mean that you should. This interface is only sufficient for performing factorizations, and so that limits the scaling choices, the types of A that can be supported, etc. Instead, linear solves within packages should use LinearSolve.jl. Similarly, nonlinear solves should use NonlinearSolve.jl. Optimization should use Optimization.jl. Etc. This allows the full generic choice to be given to the user without depending on every solver package (effectively recreating the generic interfaces within each package).","category":"page"},{"location":"developers/design-principles/#Functions-should-capture-one-underlying-principle","page":"Design Principles","title":"Functions should capture one underlying principle","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Functions mean one thing. Every dispatch of + should be \"the meaning of addition on these types\". While in theory you could add dispatches to + that mean something different, that will fail in generic code for which + means addition. Thus, for generic code to work, code needs to adhere to one meaning for each function. Every dispatch should be an instantiation of that meaning.","category":"page"},{"location":"developers/design-principles/#Internal-choices-should-be-exposed-as-options-whenever-possible","page":"Design Principles","title":"Internal choices should be exposed as options whenever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"Whenever possible, numerical values and choices within scripts should be exposed as options to the user. This promotes code reusability beyond the few cases the author may have expected.","category":"page"},{"location":"developers/design-principles/#Prefer-code-reuse-over-rewrites-whenever-possible","page":"Design Principles","title":"Prefer code reuse over rewrites whenever possible","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"If a package has a function you need, use the package. Add a dependency if you need to. If the function is missing a feature, prefer to add that feature to said package and then add it as a dependency. If the dependency is potentially troublesome, for example because it has a high load time, prefer to spend time helping said package fix these issues and add the dependency. Only when it does not seem possible to make the package \"good enough\" should using the package be abandoned. If it is abandoned, consider building a new package for this functionality as you need it, and then make it a dependency.","category":"page"},{"location":"developers/design-principles/#Prefer-to-not-shadow-functions","page":"Design Principles","title":"Prefer to not shadow functions","text":"","category":"section"},{"location":"developers/design-principles/","page":"Design Principles","title":"Design Principles","text":"In Julia, two functions can share the same name if they belong to different namespaces. For example, X.f and Y.f can be two different functions, with different dispatches, but the same name. This should be avoided whenever possible. Instead of creating MyPackage.sort, consider adding dispatches to Base.sort for your types if these new dispatches match the underlying principle of the function. If they don't, it would be preferable to use a different name. While using MyPackage.sort is not conflicting, it is going to be confusing for most people unfamiliar with your code, so MyPackage.special_sort would be more helpful to newcomers reading the code.","category":"page"},{"location":"developers/style-guide/#style","page":"Style Guide","title":"Style Guide","text":"","category":"section"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"This section describes the coding style rules that apply to our code and that we recommend you to use it also.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"In some cases, our style guide diverges from Julia's official Style Guide (Please read it!). All such cases will be explicitly noted and justified.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"Our style guide adopts many recommendations from the BlueStyle. Please read the BlueStyle before contributing to this package. If these guidelines are not followed, your pull requests may not be accepted.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"info: Info\nThe style guide is always a work in progress, and not all EquationOfStateRecipes code follows the rules. When modifying EquationOfStateRecipes, please fix the style violations of the surrounding code (i.e., leave the code tidier than when you started). If large changes are needed, consider separating them into another pull request.","category":"page"},{"location":"developers/style-guide/#Formatting","page":"Style Guide","title":"Formatting","text":"","category":"section"},{"location":"developers/style-guide/#Run-JuliaFormatter","page":"Style Guide","title":"Run JuliaFormatter","text":"","category":"section"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"EquationOfStateRecipes uses JuliaFormatter as an auto-formatting tool.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"We use the options contained in .JuliaFormatter.toml.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"To format your code, cd to the EquationOfStateRecipes directory, then run:","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"julia> using Pkg\n\njulia> Pkg.add(\"JuliaFormatter\")\n\njulia> using JuliaFormatter: format\n\njulia> format(\"docs\"); format(\"src\"); format(\"test\")","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"info: Info\nA continuous integration check verifies that all PRs made to EquationOfStateRecipes have passed the formatter.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"The following sections outline extra style guide points that are not fixed automatically by JuliaFormatter.","category":"page"},{"location":"developers/style-guide/#Use-the-Julia-extension-for-Visual-Studio-Code","page":"Style Guide","title":"Use the Julia extension for Visual Studio Code","text":"","category":"section"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"Please use Visual Studio Code with the Julia extension to edit, format, and test your code. For the time being, we do not recommend using editors other than Visual Studio Code to edit your code.","category":"page"},{"location":"developers/style-guide/","page":"Style Guide","title":"Style Guide","text":"This extension already has JuliaFormatter integrated. So to format your code, follow the steps listed here.","category":"page"},{"location":"lib/public/#Public-API","page":"Public API","title":"Public API","text":"","category":"section"},{"location":"lib/public/#Contents","page":"Public API","title":"Contents","text":"","category":"section"},{"location":"lib/public/","page":"Public API","title":"Public API","text":"Pages = [\"public.md\"]\nDepth = 2","category":"page"},{"location":"lib/public/#Index","page":"Public API","title":"Index","text":"","category":"section"},{"location":"lib/public/","page":"Public API","title":"Public API","text":"Pages = [\"public.md\"]","category":"page"},{"location":"lib/public/#Public-interface","page":"Public API","title":"Public interface","text":"","category":"section"},{"location":"lib/public/","page":"Public API","title":"Public API","text":"For detailed examples, please refer to section \"Examples\".","category":"page"},{"location":"lib/public/","page":"Public API","title":"Public API","text":"plot\nenergyplot\npressureplot\nbulkmodulusplot\nenergypressureplot","category":"page"},{"location":"lib/public/#RecipesBase.plot","page":"Public API","title":"RecipesBase.plot","text":"plot(eos::EnergyEquation, volumes, args...; kw...)\nplot(eos::PressureEquation, volumes, args...; kw...)\nplot(eos::BulkModulusEquation, volumes, args...; kw...)\nplot!(eos::EnergyEquation, volumes, args...; kw...)\nplot!(eos::PressureEquation, volumes, args...; kw...)\nplot!(eos::BulkModulusEquation, volumes, args...; kw...)\nplot!(plotobj, eos::EnergyEquation, volumes, args...; kw...)\nplot!(plotobj, eos::PressureEquation, volumes, args...; kw...)\nplot!(plotobj, eos::BulkModulusEquation, volumes, args...; kw...)\n\nPlot the energy/pressure/bulk modulus versus volumes curve given an equation of state.\n\n\n\n\n\n","category":"function"},{"location":"lib/public/#EquationOfStateRecipes.energyplot","page":"Public API","title":"EquationOfStateRecipes.energyplot","text":"energyplot(params::Parameters, volumes, args...; kw...)\nenergyplot!(params::Parameters, volumes, args...; kw...)\nenergyplot!(plotobj, params::Parameters, volumes, args...; kw...)\n\nPlot the energy versus volumes curves given the parameters of equations of state.\n\n\n\n\n\n","category":"function"},{"location":"lib/public/#EquationOfStateRecipes.pressureplot","page":"Public API","title":"EquationOfStateRecipes.pressureplot","text":"pressureplot(params::Parameters, volumes, args...; kw...)\npressureplot!(params::Parameters, volumes, args...; kw...)\npressureplot!(plotobj, params::Parameters, volumes, args...; kw...)\n\nPlot the pressure versus volumes curves given the parameters of equations of state.\n\n\n\n\n\n","category":"function"},{"location":"lib/public/#EquationOfStateRecipes.bulkmodulusplot","page":"Public API","title":"EquationOfStateRecipes.bulkmodulusplot","text":"bulkmodulusplot(params::Parameters, volumes, args...; kw...)\nbulkmodulusplot!(params::Parameters, volumes, args...; kw...)\nbulkmodulusplot!(plotobj, params::Parameters, volumes, args...; kw...)\n\nPlot the bulk modulus versus volumes curves given the parameters of equations of state.\n\n\n\n\n\n","category":"function"},{"location":"lib/public/#EquationOfStateRecipes.energypressureplot","page":"Public API","title":"EquationOfStateRecipes.energypressureplot","text":"energypressureplot(params::Parameters, volumes, args...; layout=(1, 2), kw...)\nenergypressureplot!(params::Parameters, volumes, args...; layout=(1, 2), kw...)\nenergypressureplot!(plotobj, params::Parameters, volumes, args...; layout=(1, 2), kw...)\n\nCreate a graph that shows the energy/pressure versus volume curves using the given parameters of equations of state on the same horizontal axis.\n\nwarning: Warning\nTo use this function, you must specify the layout keyword argument as either (1, 2) or (2, 1)!\n\n\n\n\n\n","category":"function"},{"location":"#EquationOfStateRecipes","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Documentation for EquationOfStateRecipes.","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"See the Index for the complete list of documented functions and types.","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"The code, which is hosted on GitHub, is tested using various continuous integration services for its validity.","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"This repository is created and maintained by @singularitti, and contributions are highly welcome.","category":"page"},{"location":"#Package-features","page":"EquationOfStateRecipes","title":"Package features","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"This package contains recipes for EquationsOfStateOfSolids.jl which work with Plots.jl.","category":"page"},{"location":"#Installation","page":"EquationOfStateRecipes","title":"Installation","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"The package can be installed with the Julia package manager. From the Julia REPL, type ] to enter the Pkg mode and run:","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"pkg> add EquationOfStateRecipes","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Or, equivalently, via Pkg.jl:","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"import Pkg; Pkg.add(\"EquationOfStateRecipes\")","category":"page"},{"location":"#Documentation","page":"EquationOfStateRecipes","title":"Documentation","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"STABLE — documentation of the most recently tagged version.\nDEV — documentation of the in-development version.","category":"page"},{"location":"#Project-status","page":"EquationOfStateRecipes","title":"Project status","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"The package is developed for and tested against Julia v1.6 and above on Linux, macOS, and Windows.","category":"page"},{"location":"#Questions-and-contributions","page":"EquationOfStateRecipes","title":"Questions and contributions","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"You can post usage questions on our discussion page.","category":"page"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"We welcome contributions, feature requests, and suggestions. If you encounter any problems, please open an issue. The Contributing page has a few guidelines that should be followed when opening pull requests and contributing code.","category":"page"},{"location":"#Manual-outline","page":"EquationOfStateRecipes","title":"Manual outline","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Pages = [\n \"man/installation.md\",\n \"man/examples.md\",\n \"man/troubleshooting.md\",\n \"developers/contributing.md\",\n \"developers/style-guide.md\",\n \"developers/design-principles.md\",\n]\nDepth = 3","category":"page"},{"location":"#Library-outline","page":"EquationOfStateRecipes","title":"Library outline","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Pages = [\"lib/public.md\", \"lib/internals.md\"]","category":"page"},{"location":"#main-index","page":"EquationOfStateRecipes","title":"Index","text":"","category":"section"},{"location":"","page":"EquationOfStateRecipes","title":"EquationOfStateRecipes","text":"Pages = [\"lib/public.md\"]","category":"page"},{"location":"man/examples/#Examples","page":"Examples","title":"Examples","text":"","category":"section"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Pages = [\"examples.md\"]\nDepth = 2","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Here is an example of plotting four equations of state in one figure with energy and pressure versus volume.","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"We can plot these parameters directly using shorthand functions such as energyplot, pressureplot, bulkmodulusplot:","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"using EquationOfStateRecipes\nusing EquationsOfStateOfSolids\nusing Plots\n\nbm = BirchMurnaghan3rd(40.989265727926536, 0.5369258245609575, 4.178644231927682, -10.8428039082991);\nm = Murnaghan1st(41.13757924604193, 0.5144967654094419, 3.9123863221667086, -10.836794510844241);\npt = PoirierTarantola3rd(40.86770643567071, 0.5667729960008748, 4.331688934947504, -10.851486685029437);\nv = Vinet(40.9168756740098, 0.5493839427843088, 4.3051929493806345, -10.846160810983498);\n\nplot(; legend=true);\nbulkmodulusplot!(bm; label=\"Birch–Murnaghan\");\nbulkmodulusplot!(bm; label=\"Murnaghan\");\nbulkmodulusplot!(pt; label=\"Poirier–Tarantola\");\nbulkmodulusplot!(v; label=\"Vinet\");\ntitle!(raw\"$B(V)$\");\nsavefig(\"bv.svg\"); nothing # hide","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"(Image: )","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Of course, we can construct four equations of state from those parameters and plot them:","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"bmeos = EnergyEquation(bm);\nmeos = EnergyEquation(m);\npteos = EnergyEquation(pt);\nveos = EnergyEquation(v);\n\nplot(; legend=true);\nplot!(bmeos; label=\"Birch–Murnaghan\");\nplot!(meos; label=\"Murnaghan\");\nplot!(pteos; label=\"Poirier–Tarantola\");\nplot!(veos; label=\"Vinet\");\ntitle!(raw\"$E(V)$\");\nsavefig(\"eos.svg\"); nothing # hide","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"(Image: )","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Or, we can plot dual plots with energypressureplot:","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"plot(; layout=(1, 2))\nenergypressureplot!(bm; label=\"Birch–Murnaghan\");\nenergypressureplot!(m; label=\"Murnaghan\");\nenergypressureplot!(pt; label=\"Poirier–Tarantola\");\nenergypressureplot!(v; label=\"Vinet\");\nsavefig(\"energypressureplot.svg\"); nothing # hide","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"(Image: )","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"Also, we can add units to these equations of state without any difficulty:","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"using Unitful, UnitfulAtomic\n\nbm = BirchMurnaghan3rd(40.989265727926536u\"angstrom^3\", 0.5369258245609575u\"Ry/angstrom^3\", 4.178644231927682, -10.8428039082991u\"Ry\");\nm = Murnaghan1st(41.13757924604193u\"angstrom^3\", 0.5144967654094419u\"Ry/angstrom^3\", 3.9123863221667086, -10.836794510844241u\"Ry\");\npt = PoirierTarantola3rd(40.86770643567071u\"angstrom^3\", 0.5667729960008748u\"Ry/angstrom^3\", 4.331688934947504, -10.851486685029437u\"Ry\");\nv = Vinet(40.9168756740098u\"angstrom^3\", 0.5493839427843088u\"Ry/angstrom^3\", 4.3051929493806345, -10.846160810983498u\"Ry\");\n\nenergypressureplot(bm; label=\"Birch–Murnaghan\", layout=(2, 1));\nenergypressureplot!(m; label=\"Murnaghan\");\nenergypressureplot!(pt; label=\"Poirier–Tarantola\");\nenergypressureplot!(v; label=\"Vinet\");\nsavefig(\"units.svg\"); nothing # hide","category":"page"},{"location":"man/examples/","page":"Examples","title":"Examples","text":"(Image: )","category":"page"},{"location":"man/installation/#Installation-Guide","page":"Installation Guide","title":"Installation Guide","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Pages = [\"installation.md\"]\nDepth = 2","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Here are the installation instructions for package EquationOfStateRecipes. If you have trouble installing it, please refer to our Troubleshooting page for more information.","category":"page"},{"location":"man/installation/#Install-Julia","page":"Installation Guide","title":"Install Julia","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"First, you should install Julia. We recommend downloading it from its official website. Please follow the detailed instructions on its website if you have to build Julia from source. Some computing centers provide preinstalled Julia. Please contact your administrator for more information in that case. Here's some additional information on how to set up Julia on HPC clusters.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"If you have Homebrew installed, open the Terminal app and type","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"brew install julia","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"to install it as a formula.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"If you are also using macOS and want to install it as a prebuilt binary app, type","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"brew install --cask julia","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"instead.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"If you want to install multiple Julia versions in the same operating system, a recommended way is to use a version manager such as Juliaup. First, install Juliaup. Then, run","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"juliaup add release\njuliaup default release","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"to configure the julia command to start the latest stable version of Julia (this is also the default value).","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Here is a short video introduction to Juliaup made by its authors.","category":"page"},{"location":"man/installation/#Which-version-should-I-pick?","page":"Installation Guide","title":"Which version should I pick?","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"You can install the current stable release or the long-term support (LTS) release.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"The current stable release is the latest release of Julia. It has access to newer features, and is likely faster.\nThe long-term support release is an older version of Julia that has continued to receive bug and security fixes. However, it may not have the latest features or performance improvements.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"For most users, you should install the current stable release, and whenever Julia releases a new version of the current stable release, you should update your version of Julia. Note that any code you write on one version of the current stable release will continue to work on all subsequent releases.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"For users in restricted software environments (e.g., your enterprise IT controls what software you can install), you may be better off installing the long-term support release because you will not have to update Julia as frequently.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Versions above v1.3, especially the latest stable ones, are strongly recommended. This package is highly unlikely to work on v1.0 and earlier versions. Since the Julia team has set v1.6 as the LTS release, we will gradually drop support for versions below v1.6.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Julia and Julia packages support multiple operating systems and CPU architectures; check this table to see if it can be installed on your machine. For Mac computers with M-series processors, this package and its dependencies may not work. Please install the Intel-compatible version of Julia (for macOS x86-64) if any platform-related error occurs.","category":"page"},{"location":"man/installation/#Install-the-package","page":"Installation Guide","title":"Install the package","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Now I am using macOS as a standard platform to explain the following steps:","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Open the Terminal app, and type julia to start an interactive session (known as the REPL).\nRun the following commands and wait for them to finish:\njulia> using Pkg\n\njulia> Pkg.update()\n\njulia> Pkg.add(\"EquationOfStateRecipes\")\nRun\njulia> using EquationOfStateRecipes\nand have fun!\nPlease keep the Julia session active while using it. Restarting the session may take some time.","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"If you want to install the latest in-development (probably buggy) version of EquationOfStateRecipes, type","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"using Pkg\nPkg.update()\npkg\"add https://github.com/MineralsCloud/EquationOfStateRecipes.jl\"","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"in the second step above.","category":"page"},{"location":"man/installation/#Update-the-package","page":"Installation Guide","title":"Update the package","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Please watch our GitHub repository for new releases. Once we release a new version, you can update EquationOfStateRecipes by typing","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"using Pkg\nPkg.update(\"EquationOfStateRecipes\")\nPkg.gc()","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"in the Julia REPL.","category":"page"},{"location":"man/installation/#Uninstall-and-then-reinstall-the-package","page":"Installation Guide","title":"Uninstall and then reinstall the package","text":"","category":"section"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"Sometimes errors may occur if the package is not properly installed. In this case, you may want to uninstall and reinstall the package. Here is how to do that:","category":"page"},{"location":"man/installation/","page":"Installation Guide","title":"Installation Guide","text":"To uninstall, in a Julia session, run\njulia> using Pkg\n\njulia> Pkg.rm(\"EquationOfStateRecipes\")\n\njulia> Pkg.gc()\nPress Ctrl+D to quit the current session. Start a new Julia session and reinstall EquationOfStateRecipes.","category":"page"}] }