Merge pull request #115 from bmad-sim/documentation

Documentation

README.md

@@ -1,63 +1,56 @@
-# AtomicAndPhysicalConstants
+# AtomicAndPhysicalConstants.jl
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://bmad-sim.github.io/AtomicAndPhysicalConstants.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://bmad-sim.github.io/AtomicAndPhysicalConstants.jl/dev/)
 [![Build Status](https://github.com/bmad-sim/AtomicAndPhysicalConstants.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/bmad-sim/AtomicAndPhysicalConstants.jl/actions/workflows/CI.yml?query=branch%3Amain)
 
 
+# AtomicAndPhysicalConstants.jl
 
+`AtomicAndPhysicalConstants.jl` provides a quick way to access information about different species and physical constants.
 
-AtomicAndPhysicalConstants is a package which provides numerical constants and
-simulation-ready objects for tracking through an accelerator lattice, as well as
-other possible scenarios. It includes information about a number of hadrons and
-fundamental particles, listed below; also included is detailed information about
-every isotope of every atomic element documented by NIST.
-
-The numerical constants are:
-- `c_light`: speed of light
-- `h_planck`: Planck's constant
-- `h_bar_planck`: Planck's constant / 2pi
-- `mu_0_vac`: vacuum permeability
-- `eps_0_vac`: vacuum permittivity
-- `fine_structure`: fine structure constant
-- `N_avogadro`: Avogadro's constant
-- `m_electron`: electron mass
-- `r_e`: electron radius
-- `anom_mag_moment_electron`: anomalous magnetic moment of the electron
-- `m_proton`: proton mass
-- `r_p`: proton radius
-- `anom_mag_moment_proton`: anomalous magnetic moment of the proton
-- `m_neutron`: neutron mass
-- `anom_mag_moment_neutron`: anomalous magnetic moment of the neutron
-- `m_muon`: muon mass
-- `anom_mag_moment_muon`: anomalous magnetic moment of the muon
-- `m_helion`: Helion (He3 nucleus) mass
-- `anom_mag_moment_He3`: anomalous magnetic moment of the helion
-- `m_deuteron`: deuteron mass
-- `anom_mag_moment_deuteron`: anomalous magnetic moment of the deuteron
-- `m_pion_0`: mass of a neutral pion
-- `m_pion_charged`: mass of a charged pion
-- `kg_per_amu`: mass conversion factor between kg and dalton
-- `eV_per_amu`: mass conversion factor between eV/c^2 and dalton
-
-
-Subatomic particles included with information about
-charge, mass, anomalous magnetic moment, and spin
-are:
-- `photon`
-- `pion0`
-- `pion+`
-- `pion-`
-- `muon`
-- `antimuon`
-- `electron`
-- `positron`
-- `proton`
-- `anti-proton`
-- `neutron`
-- `anti-neutron`
-- `deuteron`
-- `anti-deuteron`
-
-
-In addition, a collection of all the isotopes documented by NIST
-is included. Values may be updated with setIsos()
+It is designed to provide atomic and physical constants including things like the speed of light, subatomic particle properties, atomic isotope properties, etc. 
+
+Values are obtained from CODATA (Committee on Data of the International Science Council), NIST (National Institute of Standards and Technology), and PDG (Particle Data Group). This package enables users to access and customize units for the constants. 
+
+The package is compatible with Julia's `Unitful.jl` library for convenient unit manipulation. 
+
+`AtomicAndPhysicalConstants.jl` has the following main features and advantages:
+
+1. **Simple Unit Manipulation**: Users can define the units they want to use in a simple and consistent way. `Unitful.jl` provides a simple way to do unit conversion and calculations.
+2. **Rigorous and Up-to-Date Data**: We uses the most updated values from creditable sources. We also provided the option to use past data for specific purposes.
+3. **Simple usage**: Users can access data of a wide range of particles and physic constants by simply defining a species with their name or call a variable in the namespace. 
+
+## Setup
+## Basic Usage
+
+### Defining Physical Constants
+
+The macro `@APCdef` helps you define a set of useful physical constants in your namespace. 
+
+```julia
+julia> @APCdef
+julia> C_LIGHT
+2.99792458e8
+```
+
+Users have the options for choosing the type and unit of the constants, see [this page](units.md)
+
+### Defining Species
+
+The constructor `Species()` helps you create a structure with all the information of the species stored in it.
+
+```julia
+julia> e = Species("electron")
+julia> hydrogen = Species("H")
+```
+
+You could use getter functions to access its properties or directly calling its fields. 
+
+```julia
+julia> massof(e)
+510998.95069
+julia> hydrogen.spin
+1.0 h_bar
+```
+
+See more about `Species()` constructors and getter functions [here](species.md)

docs/make.jl

@@ -2,14 +2,14 @@ using Documenter, AtomicAndPhysicalConstants
 
 makedocs(
   sitename="AtomicAndPhysicalConstants.jl",
-  authors="Alex Coxe et al.",
+  authors="Alex Coxe, Lixing Li, Matt Signorelli, David Sagan et al.",
   format=Documenter.HTMLWriter.HTML(size_threshold=nothing),
   pages=
   [
     "Home" => "index.md",
-    "Set Units" => "set_units.md",
-    "Constants Getter Functions" => "constants.md",
-    "Constants Used" => "constants_used.md"
+    "APCdef" => "units.md",
+    "Constants" => "constants.md",
+    "Species" => "species.md"
   ]
 )
 

docs/src/constants.md

@@ -1,58 +1,54 @@
 
 # Constants 
 
-Constants are accessed by a getter function. If a unit is provided, then the value with that unit is returned. If units is not provided, then the units will be in the units determined by `setunits()`. For Example:
+## Available Constants
+The macro `@APCdef` defines a set of physical constants with the provided set of units (For more details, see [this page](units.md)). The following example is how to use the macro and the physical constants.
 
 ```julia
-c_light(u"km/s") # return 299792.458 km s⁻¹
-
-setunits() # set units to ACCELERATOR unit system, where speed unit is m/s
-
-c_light() #return 2.99792458e8 m s⁻¹
+julia> @APCdef
+julia> C_LIGHT
+2.99792458e8
 ```
 
-## Here is a list of constants getter functions:
+### Constants Defined by @APCdef
 
-#### Speed of light: `c_light()`
-#### Planck's constant: `h_planck()`
-#### Reduced Planck's constant: `h_bar_planck()`
-#### Classical electron radius: `r_e()`
-#### Classical proton radius: `r_p()`
-#### Elementary charge:  `e_charge()`
-#### Vacuum permeability: `mu_0_vac()`
-#### Permittivity of free space: `eps_0_vac()`
-#### Classical Radius Factor: `classical_radius_factor()`
-#### Fine structure constant: `fine_structure()`
-#### Avogadro's constant: `N_avogadro()`
+- Speed of light: `C_LIGHT`
+- Planck's constant: `H_PLANCK`
+- Reduced Planck's constant: `H_BAR_PLANCK`
+- Classical electron radius: `R_E`
+- Classical proton radius: `R_P`
+- Elementary charge:  `E_CHARGE`
+- Vacuum permeability: `MU_0_VAC`
+- Permittivity of free space: `EPS_0_VAC`
+- Classical Radius Factor: `CLASSICAL_RADIUS_FACTOR`
+- Fine structure constant: `FINE_STRUCTURE`
+- Avogadro's constant: `N_AVOGADRO`
 
-## Species Mass and Charge
+### Species Mass and Charge
 
-To access mass or charge of a species, use `massof()` getter function for mass, and `chargeof()` getter function for charge. Similarly, if a unit is not provided, the function will return unit defined by `setunits()`. For Example:
+To access mass or charge of a species, use `massof()` getter function for mass, and `chargeof()` getter function for charge. The function will return unit given to `@APCdef`. For Example:
 
 ```julia
-e = Species("electron") 
+julia> e = Species("electron") 
+
+julia> @APCdef unitsystem = ACCELERATOR unitful = true # set units to ACCELERATOR unit system, where mass unit is eV/c^2 and charge unit is elementary charge
 
-setunits() # set units to ACCELERATOR unit system, where mass unit is eV/c^2 and charge unit is elementary charge
+julia> massof(e) 
+510998.95069 eV c⁻²
 
-massof(e) # return 510998.95069 eV c⁻²
+julia> chargeof(e)
+-1.0 e
 
-massof(e,u"MeV/c^2") # return 0.51099895069 MeV c⁻²
+```
 
-chargeof(e) # return -1.0 e
+## Constants Sources and Updates
 
-chargeof(e, u"C") #return -1.602176634e-19 C
+The data for the constants are provided by CODATA. Users have the freedom to choose the year of CODATA in `@APCdef`. For example: 
+```julia
+julia> @APCdef CODATA = 2018
 ```
+The data are downloaded to the local file.
+
+The isotope data are provided by NIST. We extract the isotope data from their database. The NIST doesn't store old releases, so the isotope data will always be the newest release.
 
-### Here is a list of species where you can find its mass or charge in a similar way
-
-  - "pion0"
-  - "neutron"
-  - "deuteron"
-  - "pion+"
-  - "proton"
-  - "photon"
-  - "electron" 
-  - "anti-proton"
-  - "muon"
-  - "pion-"
-  - "anti-deuteron"
+The pion0 and pion+- data are provided by PDG(Particle Data Group). We extracted the data from the database of **pdgapi.lbl.gov**

docs/src/constants_used.md

@@ -39,7 +39,27 @@ Constants are pulled from the NIST table of the **2022 CODATA release**. Note th
 #### Joules per eV: `J_per_eV` = 1.602176634e-19
 
 
-
+Subatomic particles included with information about
+charge, mass, anomalous magnetic moment, and spin
+are:
+- `photon`
+- `pion0`
+- `pion+`
+- `pion-`
+- `muon`
+- `antimuon`
+- `electron`
+- `positron`
+- `proton`
+- `anti-proton`
+- `neutron`
+- `anti-neutron`
+- `deuteron`
+- `anti-deuteron`
+
+
+In addition, a collection of all the isotopes documented by NIST
+is included. Values may be updated with setIsos()
 
 
 

docs/src/index.md

@@ -1,7 +1,50 @@
 # AtomicAndPhysicalConstants.jl
 
+`AtomicAndPhysicalConstants.jl` provides a quick way to access information about different species and physical constants.
 
-`AtomicAndPhysicalConstants.jl` provides a quick way to store informations about different atomic species and other physical constants
+It is designed to provide atomic and physical constants including things like the speed of light, subatomic particle properties, atomic isotope properties, etc. 
 
+Values are obtained from CODATA (Committee on Data of the International Science Council), NIST (National Institute of Standards and Technology), and PDG (Particle Data Group). This package enables users to access and customize units for the constants. 
+
+The package is compatible with Julia's `Unitful.jl` library for convenient unit manipulation. 
+
+`AtomicAndPhysicalConstants.jl` has the following main features and advantages:
+
+1. **Simple Unit Manipulation**: Users can define the units they want to use in a simple and consistent way. `Unitful.jl` provides a simple way to do unit conversion and calculations.
+2. **Rigorous and Up-to-Date Data**: We uses the most updated values from creditable sources. We also provided the option to use past data for specific purposes.
+3. **Simple usage**: Users can access data of a wide range of particles and physic constants by simply defining a species with their name or call a variable in the namespace. 
+
+## Setup
 ## Basic Usage
-Call function `setunits()` to initialize the constants to your preferred units.
+
+### Defining Physical Constants
+
+The macro `@APCdef` helps you define a set of useful physical constants in your namespace. 
+
+```julia
+julia> @APCdef
+julia> C_LIGHT
+2.99792458e8
+```
+
+Users have the options for choosing the type and unit of the constants, see [this page](units.md)
+
+### Defining Species
+
+The constructor `Species()` helps you create a structure with all the information of the species stored in it.
+
+```julia
+julia> e = Species("electron")
+julia> hydrogen = Species("H")
+```
+
+You could use getter functions to access its properties or directly calling its fields. 
+
+```julia
+julia> massof(e)
+510998.95069
+julia> hydrogen.spin
+1.0 h_bar
+```
+
+See more about `Species()` constructors and getter functions [here](species.md)