This is a JS library for finding the sun & moon's position. It was ported from sowngwala which is another library that I wrote in Rust.
As it is mentioned in the original library, majority of calculation logic are based on Peter Duffett-Smith "Practical Astronomy With Your Calculator" (The Press Syndicate of the University of Cambridge, 1988).
"sowngwala" means "one who is professional at the sun" in Belter language which is from a sci-fi TV series "The Expanse (2015)".
See changelog.
When you want to find the position of the sun, it usually means 2 things:
- Physical Observation
- You want to know where the sun will physically appear at certain time and space.
- For this, you want the position either in "Equatorial" or "Horizontal" coordinate system.
- If you want "Equatorial", use sun_equatorial_from_generic_datetime
- If you want "Horizontal", use sun_horizontal_from_generic_datetime
- Astrological Calculation
- Your astrological system asks you to know the sun's position.
- Usually, you want the position in "Ecliptic" coordinate system (so that you will get "latitude (β)" and "longitude (λ)" for the given time and space)
- Use sun_ecliptic_from_generic_datetime
Not only will sun_horizontal_from_generic_datetime return the sun's "Horizontal" position, but you will notice the result also contains that of "Ecliptic" and "Equatorial". This is because you first need to know "Ecliptic" in order to find the sun's position. Once you find "Ecliptice", then it is converted to "Equatorial", and finally to "Horizontal". Thus, when you get "Horizontal", the method will also return all the by-products of the calculations.
Now, I have 2 examples demonstrated bellow. One is for the browser runtime (loading the library in your page), and another for NPM module use (for a bundled ES6 app). For both, it illustrates the use of sun_equatorial_from_generic_datetime.
If you want more examples, you can see how I implemented sun_ecliptic_from_generic_datetime for the demo page, and the source codes are found in src.check (specifically, it is in _calculate_sun_position inside src.check/controllers/event_listener.js).
This is how you want to directly use sowngwala-js in your page.
The context is exposed globally as Sowngwala,
and you can use any of the method provided.
<html>
<body>
<script src="https://{YOUR_SERVER_PATH}/sowngwala-0.3.0.js"></script>
<script type="text/javascript">
window.addEventListener('load', () => {
const { NaiveDateTime } = Sowngwala.chrono;
const { sun_equatorial_from_generic_datetime } = Sowngwala.sun;
// Find out the sun's
// Equatorial position
// for July 1, 1988 (UTC)
const utc = NaiveDateTime.from_ymd(
1988,
7,
27,
);
const { coord } =
sun_equatorial_from_generic_datetime(utc);
// right ascension (α)
const asc = coord.asc;
// declination (δ)
const dec = coord.dec;
console.log('asc:', asc.print()); // 8°26'4.0
console.log('dec:', dec.print()); // 19°12'42.5
});
</script>
</body>
</html>As mentioned in the beginning, the above is for the Equatorial position, and it is advised that you check out _calculate_sun_position in src.check for it contains a full example of finding the Horizontal (which also illustrate the use of local standard time and observer's latitude and longitude).
If you wish to include sowngwala-js in your bunlde, this is how.
Since sowngwala-js has not yet being published as a NPM package,
you need to directly install from this Github repo.
In your package.json, add the following to "dependencies":
"dependencies": {
"sowngwala-js": "git://github.com/minagawah/sowngwala-js.git",
}Once installed, begin writing codes. Implementations are about the same as the one for the runtime.
import {
NaiveDateTime,
sun_equatorial_from_generic_datetime,
} from 'sowngwala';
// Rest of the codes are
// the same as the one
// for the runtime...As mentioned, check out _calculate_sun_position in src.check for the Horizontal position (and of local standard time and observer's latitude and longitude).
You can calculate the position of the moon as well. If you wish the Ecliptic position, the method is available as well.
import {
NaiveDateTime,
moon_pos_equatorial,
} from 'sowngwala';
const utc = NaiveDateTime.from_ymd_hms(
1979,
2,
26,
16,
0,
0
);
const coord = moon_pos_equatorial(utc);
const asc = coord.asc; // right ascension (α)
const dec = coord.dec; // declination (δ)
const asc_hms = `${asc.hour()}°${asc.minute()}'${asc.second()}"`;
const dec_hms = `${dec.hour()}°${dec.minute()}'${dec.second()}"`;
console.log('asc:', asc_hms); // 22°33'28.7
console.log('dec:', dec_hms); // -8°00'57.6First of all, install NPM packages:
nvm use
npm install
To run Jest unit tests, do this:
npm run test
To emit *.d.ts files to types:
npm run type:generate
To emit JSDoc documents to jsdoc:
npm run jsdoc
To build (and emit bundles to dist):
npm run build
To launch Webpack devServer to check the behaviors
by serving the check page I have in src.check/check.html:
npm run dev
You may notice the repo contains a lot of
web-related NPM packages, and it seems
strange for a library containing
only mathematical calculations.
It has web-related NPM packages
only because I have a check page
which runs when you npm run dev.
So, they have nothing to do with the implementations of the library itself.
When it comes to finding the Equatorial position of the sun, it all begins with sun_equatorial_from_generic_datetime. With a given a date, it returns EquaCoord. However, majority of the calculations are done in sun_ecliptic_from_generic_datetime.
Refer to p.91 of Peter Duffett-Smith's "Practical Astronomy With Your Calculator" (1988) where he describes 10 steps to calculate the Equatorial position of the sun.
Step 1 aims to find "day number" which is the number of days since the beginning of the year in concern, and is calculated with day_number_from_generic_date.
Next up, we have Step 2 which is to find days since January 0th of 1990. This is the epoch date that his book supposes to base his calculations on, and is calculated with days_since_1990.
From Step 3 to Step 10 is covered by longitude_and_mean_anomaly. As the name suggests, it takes the number of days since 1900, and will return (1) lng ("λ" or "Sun's longitude"), and (2) mean_anom ("M" or "Mean Anomaly") for the date.
An additional note for Step 3 to Step 10 where Step 6 is covered by find_kepler which itself consists of a recursive function for finding "Mean anomaly (M)" and "Eccentric anomaly (E)" using Kepler's equation.
Although this is a libray, it has web related NPM modules installed because we want to run Webpack devServer to check library behaviors using src.check/check.html. Otherwise, we won't need such web related dependencies.
- core-js
- @babel/cli
- @babel/core
- @babel/preset-env
- babel-loader
- webpack
- webpack-cli
- webpack-dev-server
- file-loader
- css-loader
- style-loader
- postcss-loader
- html-webpack-plugin
- copy-webpack-plugin
- mini-css-extract-plugin
- terser-webpack-plugin
- license-webpack-plugin
- webpack-bundle-analyzer
- prettier
- eslint
- eslint-config-prettier
- Filters out all the ESLint rules which conflict with Prettier.
- eslint-plugin-prettier
- Orchestrates ESLint and Prettier together.
- @stylistic/eslint-plugin
- New way of setting rules
- postcss
- postcss-cli
- postcss-preset-env
- postcss-import
- postcss-mixins
- postcss-nested
- autoprefixer
- tailwindcss
- babel-plugin-preval
- jsdoc
- jsdoc-tsimport-plugin
jsdoc-to-markdown- High vulnerability depnding on: jsdoc-parse
- jsdoc-plugin-intersection
- typescript
- @types/ramda
- jest
- babel-jest
- rimraf
- nodemon
- concurrently
- ramda
- moment
- moment-timezone
- csv-parse
npm install --save core-js ramda moment moment-timezone;
npm install --save-dev @babel/cli @babel/core \
@babel/preset-env babel-jest babel-loader \
webpack webpack-cli webpack-dev-server \
file-loader css-loader style-loader postcss-loader \
html-webpack-plugin copy-webpack-plugin \
mini-css-extract-plugin terser-webpack-plugin \
license-webpack-plugin webpack-bundle-analyzer \
prettier eslint eslint-config-prettier eslint-plugin-prettier \
@stylistic/eslint-plugin \
postcss postcss-cli autoprefixer \
postcss-preset-env postcss-import postcss-mixins postcss-nested \
tailwindcss babel-plugin-preval \
jsdoc jsdoc-tsimport-plugin jsdoc-plugin-intersection \
typescript @types/ramda jest \
rimraf nodemon concurrently csv-parse;
Dual-licensed under either of the followings.
Choose at your option.
- The UNLICENSE (LICENSE.UNLICENSE)
- MIT license (LICENSE.MIT)
City names and longitude/latitude data used in our chec app is provided by the Pareto Software, LLC. whick is protected under CC BY 4.0 Deed. See details about the license.
https://simplemaps.com/data/world-cities