Skip to content

AGENTS.md first draft #1687

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jlnav wants to merge 8 commits into
base: develop
Choose a base branch
from
+95 −0
Open

AGENTS.md first draft #1687

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
8cbab2c
initial commit - first draft
jlnav Mar 4, 2026
fdb49a8
Merge pull request #1685 from Libensemble/release/v_1.6.0
shuds13 Mar 4, 2026
334565e
additional clarifying and infrastructure details as suggestd by gemin…
jlnav Mar 5, 2026
ee57ff7
Merge branch 'develop' into feature/agentsmd
jlnav Mar 5, 2026
72ed72b
fix typo
jlnav Mar 5, 2026
5609ac1
additional rearranging and clarifications
jlnav Mar 6, 2026
ce905d7
Merge branch 'develop' of https://github.com/Libensemble/libensemble …
jlnav Mar 6, 2026
5bf37f1
Merge branch 'develop' into feature/agentsmd
jlnav Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
Agent Contributor Guidelines and Information
============================================

Read the ``README.rst`` for an overview of libEnsemble.

- libEnsemble uses a manager-worker architecture. Points are generated by a generator and sent to a worker, which runs a simulator.
- The manager determines how and when points get passed to workers via an allocation function.
- See ``libensemble/tests/regression_tests/test_1d_sampling.py`` for a simple example of the libEnsemble interface.

Repository Layout
-----------------

- ``libensemble/`` - Source code.
- ``/alloc_funcs`` - Allocation functions. Policies for passing work between the manager and workers.
- ``/comms`` - Modules and abstractions for communication between the manager and workers.
- ``/executors`` - An interface for launching executables, often simulations.
- ``/gen_classes`` - Generators that adhere to the `gest-api` standard.
Recommended over entries from ``/gen_funcs`` that perform similar functionality.
- ``/gen_funcs`` - Generator functions. Modules for producing points for simulations.
- ``/resources`` - Classes and functions for managing compute resources for MPI tasks, libensemble workers.
- ``/sim_funcs`` - Simulator functions. Modules for running simulations or performing experiments.
- ``/tests`` - Tests.
- ``/functionality_tests`` - Primarily tests libEnsemble code only.
- ``/regression_tests`` - Tests libEnsemble code with external code. Often more closely resembles actual use-cases.
- ``/unit_tests`` - Tests for individual modules.
- ``/tools`` - Tools. Misc functions and classes to ease development.
- ``/utils`` - Utilities. Misc functions and classes used internally by multiple modules.
- ``ensemble.py`` - The primary interface for parameterizing and running libEnsemble.
- ``generators.py`` - Base classes for generators that adhere to the `gest-api` standard.
- ``history.py`` - Module for recording points that have been generated and simulation results. NumPy array.
- ``libE.py`` - libE main file. Previous primary interface for parameterizing and running libEnsemble.
- ``logger.py`` - Logging configuration.
- ``manager.py`` - Module for maintaining the history array and passing points between the workers.
- ``message_numbers.py`` - Constants that represent states of the ensemble.
- ``specs.py`` - Dataclasses for parameterizing the ensemble. Most importantly, contains ``LibeSpecs, SimSpecs, GenSpecs``.
- ``worker.py`` - Module for running generators and simulators. Communicates with the manager.
- ``version.py`` - Version file.

- ``.github/`` - GitHub actions. See ``.github/workflows/`` for the CI.
- ``docs/`` - Documentation. Check here first for information before reading the source code.
- ``examples/`` - The ``*_funcs`` and ``calling_scripts`` directories contain symlinks to examples further in the source code.
- ``/libE_submission_scripts`` - Example scripts for submitting libEnsemble jobs to HPC systems.
- ``/tutorials`` - Tutorials on how to use libEnsemble.
- ``pyproject.toml`` - Project configuration file. Contains information about the project and its dependencies.

Other files in the root directory should be self-documenting.

Information about Generators
----------------------------

- Generators are functions or objects that produce points for simulations.
- The History array is a NumPy structured array that stores points that have been generated and simulation results.
Its fields match ``sim_specs/gen_specs["out"]`` or ``vocs`` attributes, plus additional reserved fields for metadata.
- Prior to libEnsemble v1.6.0, generators were plain functions. They often ran in "persistent" mode, meaning they executed in a
long-running loop, sending and receiving points to and from the manager until the ensemble was complete.
- A ``gest-api`` or "standardized" generator is a class that at a minimum implements ``suggest`` and ``ingest`` methods, and is parameterized by a ``vocs``.
- See ``libensemble/generators.py`` for more information about the ``gest-api`` standard.
- If using a generator that adheres to the ``gest-api`` standard, or a classic persistent generator, use the ``start_only_persistent`` allocation function.
- Generators are often used for simple sampling, optimization, calibration, uncertainty quantification, and other simulation-based tasks.

General Guidelines
------------------

- If using classic ``sim_specs`` and ``gen_specs``, then ensure that ``sim_specs["out"]`` and ``gen_specs["in"]`` field names match, and vice-versa.
- As-of libEnsemble v1.6.0, ``SimSpecs`` and ``GenSpecs`` can also be parameterized by a ``vocs`` object, imported from ``gest_api.vocs`` (NOT xopt.vocs).
- ``VOCS`` contains variables, objectives, constraints, and other settings that define the problem.
See ``libensemble/tests/regression_tests/test_xopt_EI.py`` for an example of how to use it.
- An MPI distribution is not required for libEnsemble to run, but is required to use the ``MPIExecutor``. ``mpich`` is recommended.
- New tests are heavily encouraged for new features, bug fixes, or integrations. See ``libensemble/tests/regression_tests`` for examples.
- Never use destructive git commands unless explicitly requested.
- Code is in the ``black`` style. This should be enforced by ``pre-commit``.
- When writing new code, prefer the ``LibeSpecs``, ``SimSpecs``, and ``GenSpecs`` dataclasses over the classic ``sim_specs`` and ``gen_specs`` bare dictionaries.
- Read ``CONTRIBUTING.md`` for more information.
- The external ``libE-community-examples`` repository contains past use-cases, generators, and other examples.

Development Environment
-----------------------

- ``pixi`` is the recommended environment manager for libEnsemble development. See ``pyproject.toml`` for the list
of dependencies and the available testing environments.
- Enter the development environment with ``pixi shell -e dev``. This environment contains the most common dependencies for development and testing.
- For one-off commands, use ``pixi run -e dev``. This will run a single command in the development environment.
- If ``pixi`` is not available or not preferred by the user, ``pip install -e .`` can be used instead. Other dependencies may need to be installed manually.
- If committing, use ``pre-commit`` to ensure that code style and formatting are consistent. See ``.pre-commit-config.yaml`` for
the configuration and ``pyproject.toml`` for other configuration.

Testing
-------

- Run tests with the ``run-tests.py`` script: ``python libensemble/tests/run-tests.py``. See ``libensemble/tests/run-tests.py`` for usage information.
- Some tests require third party software to be installed. When developing a feature or fixing a bug, since the entire test suite will be run on Github Actions,
for local development running individual tests is sufficient.
- Individual unit tests can be run with ``pixi run -e dev pytest path/to/test_file``.
- A libEnsemble run typically outputs an ``ensemble.log`` and ``libE_stats.txt`` file in the working directory. Check these files for tracebacks or run statistics.
- An "ensemble" or "workflow" directory may also be created, often containing per-simulation output directories