Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

The Elara Handbook

Welcome to Project Elara! Project Elara is a mission of a team of committed scientists, engineers, and talented people, working across many different fields, to pass down a better world to our future generations.

Who we are

We are an organization committed to developing open-source technologies that we believe can create a better future. Our current research focus is in developing a space-based solar power system that is 100% open-source and dedicated to a sustainable, resilient, and affordable energy future. We choose to make all of our work open-source, because we want that future to be for everyone.

These are indeed lofty goals, and we realize that even trying to begin is hardly simple. Therefore, we work as a team to accomplish this mission together. To advance, share, and preserve our collective knowledge and expertise, and to build on each other’s work, we have put together this encyclopedic book. Everything you’d ever need to learn, develop, or contribute to Project Elara can be found here. And we dedicate this book to the world: the Project Elara Handbook is released into the public domain and free to view, share, remix, and download, forever.

Reading the Handbook

Aside from being Project Elara’s primary documentation, the Handbook can also be used as a comprehensive textbook for students in the sciences. It contains the majority of the content covered in a typical undergraduate course of physics and engineering, in addition to some more advanced and specific topics. Even if you’re not interested in Project Elara, we hope that the Elara Handbook can be useful as a general reference and textbook, particularly for self-learning or studying. If this is you, feel free to skip the majority of Project Elara-related content and start reading at Chapter 3.

Getting involved

Project Elara is built on a community of passionate and dedicate people - and we welcome anyone to join our team! If you would like to contribute to Project Elara, we

The newcomer’s guide

If you’re new to the Project, we are very glad to have you join us! To get started, please read How to get started in the project, which contains a complete, step-by-step guide on getting started with the Project.

Once you’ve gotten started, reading the Elara Handbook is the recommended way to learn more about the science behind our work. That said, we understand that reading technical and scientific documentation can easily be quite confusing, so we have organized the Handbook to require minimal prerequisite knowledge and background to read. For this, the Handbook is split into three main sections: Chapters 1-4 (“The Basics”) are about the fundamentals of our work, Chapters 5-12 (“The Specifics”) are about intermediate-level topics, and the remainder of the book is about advanced topics. They can be read in order, or read separately. While everyone’s learning needs are different, we give some suggestions for which of the sections to read based on your interests/comfort level with the technical sciences:

We are so grateful for each and every one of our team members, and everyone’s contributions, no matter how small, will be tracked and (eventually) added to Contributions at the end of the book. Your work brings us one step closer to changing the world for the better.

PDF version

For offline usage, a PDF version of this book can be downloaded from https://codeberg.org/elaraproject/elara-handbook/src/branch/main/dist/elara-handbook-final.pdf, although this is a slighly older version of the Handbook. We are currently working on updating our infrastructure to support automatic PDF builds for the newest version of the Handbook.

FAQs

Quickstart for developers

Do you want to contribute to making the Handbook better? Then this section is for you! First, some background: this book is written using Jupyterbook, a Python-based tool for making scientific books containing runnable code. The source code is hosted on Project Elara’s Codeberg in the elara-handbook repository. To edit the Handbook, ensure you have Git and Python installed, then clone the repository:

git clone https://codeberg.org/elaraproject/elara-handbook
cd elara-handbook

Then you can start writing! The source files of the book are written in Markdown and are located in the book/ directory. We recommend using a markdown editor like Obsidian or Zettlr which makes editing much more convenient, but this is not strictly necessary. Simply follow the below instructions:

Git information

For developers working on Windows, it is highly recommended to configure Git to automatically handle line-endings via git config --global core.autocrlf true before editing anything. See this article here which explains why it is necessary.

HTML builds

To build the book locally and see it live on your web browser, ensure you have the following installed:

To install Just, please see the instructions in its GitHub repository. It is possible to build the book without Just (see manual build instructions below), but it becomes a lot more complicated.

Automatic build

Assuming you have all the prerequisites, building the book HTML can be done with only a couple of commands:

just install # you only need to run this the first time
just serve # to start a development server

Manual build

If you want to build manually (without Just), you will first need to install Jupyterbook and all the other book dependencies. It is optional but recommended to create a Python virtual environment for this, which can be done as follows:

# for all platforms, first run:
python -m venv .venv/

# next command varies by platform:

# Unix (Mac/Linux)
source .venv/bin/activate

# Windows powershell
.venv/Scripts/Activate.ps1

# Cygwin/Git bash for windows
source .venv/Scripts/activate

Afterwards, install the Python dependencies manually, and enter into the book/ folder:

pip install -r requirements.txt
cd book/

Finally, start the development server, which will build the book and show a preview (simply navigate to http://localhost:3000 on your web browser to view it):

# You MUST run this in the book/ folder
jupyter book start

Note that the above command only renders the static content of the book (meaning that no code in the book is executed). If you want code to be executed as well (be aware this will run slower), then enter the following command:

# You MUST run this in the book/ folder
jupyter book start --execute

PDF export

The Elara Handbook can also be compiled into a standalone PDF (you might want to do this, for example, to read the Handbook offline). For this, you’ll need to have a LaTeX compiler installed. See instructions on the LaTeX website for more information.

In addition, you will also need to have [ImageMagick] installed. To install it, go to its official website’s installation page, which has detailed instructions for how to install ImageMagick.

To build the book PDF, we offer two different options for building the PDF, depending on the degree of manual control you want. We strongly recommend the automatic builds since it requires much less work, but the choice is up to you.

Automatic PDF builds

To build automatically, simply run:

mkdir target/ # only run this on first build
just build-pdf

This should build a file called elara-handbook.pdf in the target/ folder, and can be read right away (be aware that the build can take several minutes).

Manual PDF builds

To build manually, run the following commands:

mkdir target/ # only run this on first build
cd build/
jupyter build book --pdf

The book will be located at target/elara-handbook.pdf and can be read right away.

Optional steps for PDF builds

If you have completed all the previous step, you should have the book PDF compiled, but it will not have the cover art as in the downloadable PDF version on the Elara Handbook website. If you want the PDF to look exactly like the downloadable version, there is one additional step - you will need to append the book cover. For this, there are two options: using Ghostscript, or using pdfmerge.

Appending cover using pdfmerge

This is definitely the easier way, and recommended in general unless if you already have GhostScript application installed. Assuming you have followed the previous steps for building the PDF, simply run (in the repository root):

python -m pdfmerge target/elara-handbook.pdf book/cover.pdf target/elara-handbook.pdf

The PDF (with the cover art included) will then be available at target/elara-handbook.pdf for reading.

Appending cover using Ghostscript

If you want to use Ghostscript, make sure it is available first; you can check by running gs --version (on Windows, gswin64c --version). If you don’t have Ghostscript, you will need to install it from its downloads page. Then, from the root directory of the repository, run:

# if on Linux/macOS
gs -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=target/elara-handbook.pdf \
          -dBATCH book/cover.pdf target/elara-handbook.pdf

# if on Windows (assuming 64-bit system)
gswin64c -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=target/elara-handbook.pdf \
          -dBATCH book/cover.pdf target/elara-handbook.pdf

That’s it! Simply open target/elara-handbook.pdf and you can read the entire handbook offline.

Obsidian-specific settings

If you are using the Obsidian editor to edit pages for the Elara Handbook, there are some settings that provide a more comfortable editing experience, which we provide instructions for below.

LaTeX editing plugins

We highly recommend installing the obsidian-latex plugin, as it provides support for custom LaTeX commands (such as \mathrm for typesetting physical units) that are not shipped with Obsidian by default. We have already set up a LaTeX snippets file that should load automatically upon installing the plugin, so you can get started as fast as possible.

Additionally, you may want to install the Obsidian LaTeX suite plugin, which provides macros for faster (and more comfortable) LaTeX typing.

Hide build files and other artifacts

This is very useful to make sure Obsidian doesn’t accidentally edit the build files. To use this function, install the File Ignore plugin and enable it. Then in the plugin settings (in the “Rules” textbox) enter the following:

temp/
*.tmp
.DS_Store
Thumbs.db
_build/

Afterwards press “Hide files” and Obsidian will stop indexing the build directories, as well as config files. Note that it is also very important when building the book locally to modify the build command to:

# Again this must be run in the book/ folder of the repository
jupyter book start --path-output ._build/

This is because using the standard command jupyter book start clashes with the file ignore plugin and makes it fail!

Hide the inline titles

Go to Settings → Appearance and disable “Inline Title”.

License

All material in the Elara Handbook is dedicated to the public domain.

The Elara Handbook is dedicated to the public domain. You may freely use, redistribute (free or for a fee), copy, modify, and (most importantly of all) learn from this book. Just be aware that this book cannot be copyrighted, patented, or claimed as your own work (as it is inherently in the public domain). You may also freely plagiarize this book, make proprietary modifications to this book and/or its included source code and sell it, use this book commercially, or include this book as part of a product. We, however, do not encourage such practices, as they are fundamentally against our values, and we would hope that if you derive profit from this book, you contribute some part of your profits to helping Project Elara and its mission.

More specifically, the Handbook is dual-licensed under the Unlicense and Creative Commons CC0 License (both are public domain licenses) as it contains both traditional book content and included executable code; this is because the Unlicense is designed for source code, whereas CC0 is designed for creative works. In situations where an ambiguity arises as to which license should be applied, whichever of the two below licenses is more permissive will be regarded as the sole license to be applied across the whole work.

The Unlicense

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to https://unlicense.org/

Creative Commons CC0 1.0 Universal License

Creative Commons Legal Code

CC0 1.0 Universal

CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
HEREUNDER.

Statement of Purpose

The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an “owner”) of an original work of authorship and/or a database (each, a “Work”).

Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works (“Commons”) that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others.

For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the “Affirmer”), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights.

  1. Copyright and Related Rights. A Work made available under CC0 may be protected by copyright and related or neighboring rights (“Copyright and Related Rights”). Copyright and Related Rights include, but are not limited to, the following:

i. the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work; ii. moral rights retained by the original author(s) and/or performer(s); iii. publicity and privacy rights pertaining to a person’s image or likeness depicted in a Work; iv. rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below; v. rights protecting the extraction, dissemination, use and reuse of data in a Work; vi. database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and vii. other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof.

  1. Waiver. To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer’s Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the “Waiver”). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer’s heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer’s express Statement of Purpose.

  2. Public License Fallback. Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer’s express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer’s Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the “License”). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer’s express Statement of Purpose.

  3. Limitations and Disclaimers.

a. No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document. b. Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law. c. Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person’s Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work. d. Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work.

The basics
A basic guide to Project Elara